gusimplewhiteboard
gusimplewhiteboard.h File Reference
#include <dispatch/dispatch.h>
#include <sys/types.h>
#include <cstdbool>
#include <unistd.h>
Include dependency graph for gusimplewhiteboard.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

union  gsw_simple_message
 union type that is used to store data in shared memory More...
 
struct  gsw_simple_whiteboard_s
 the actual whiteboard in shared mem More...
 
struct  gsw_whiteboard_s
 the underlying whiteboard object More...
 

Macros

#define __block   _xblock
 
#define __block   __attribute__((__blocks__(byref)))
 
#define __has_feature(x)   0
 
#define u_int64_t   uint64_t
 
#define u_int32_t   uint32_t
 
#define u_int16_t   uint16_t
 
#define u_int8_t   uint8_t
 
#define GU_SIMPLE_WHITEBOARD_VERSION   6
 version More...
 
#define GU_SIMPLE_WHITEBOARD_GENERATIONS   4
 lifespan (max) More...
 
#define GU_SIMPLE_WHITEBOARD_BUFSIZE   128
 message len (max) More...
 
#define GSW_TOTAL_MESSAGE_TYPES   512
 message types (max) More...
 
#define GSW_NUM_RESERVED   (GSW_TOTAL_MESSAGE_TYPES/2)
 
#define GSW_TOTAL_PROCESSES   256
 maximum subscriber procs More...
 
#define GSW_NON_RESERVED_MESSAGE_TYPES   (GSW_TOTAL_MESSAGE_TYPES-GSW_NUM_RESERVED)
 
#define GSW_DEFAULT_ENV   "WHITEBOARD_NAME"
 environment variable containing the default whiteboard file name More...
 
#define GSW_DEFAULT_NAME   "guWhiteboard"
 fallback default wb More...
 
#define GSWR_BASE_NAME   "guudpwhiteboard"
 UDP whiteboard name. More...
 
#define WHITEBOARD_SIGNAL   SIGUSR2
 
#define WHITEBOARD_POLL_PERIOD   10000
 
#define GSW_NUM_TYPES_DEFINED   num_types_defined
 allow whiteboard to use old functions for whiteboard initialisation and choose which messages and consts they get More...
 

Typedefs

typedef void(* gsw_subscription_f) (struct gsw_whiteboard_s *wbd)
 
typedef union gsw_simple_message gu_simple_message
 union type that is used to store data in shared memory More...
 
typedef struct gsw_simple_whiteboard_s gu_simple_whiteboard
 the actual whiteboard in shared mem More...
 
typedef int gsw_sema_t
 
typedef struct gsw_whiteboard_s gu_simple_whiteboard_descriptor
 the underlying whiteboard object More...
 

Enumerations

enum  gsw_semaphores {
  GSW_SEM_PUTMSG , GSW_SEM_CALLBACK , GSW_SEM_MSGTYPE , GSW_SEM_PROC ,
  GSW_NUM_SEM
}
 

Functions

gu_simple_whiteboard_descriptorgsw_new_whiteboard (const char *name)
 access a named whiteboard: this is the designated constructore for C programs More...
 
gu_simple_whiteboard_descriptorgsw_new_custom_whiteboard (const char *name, const char *message_names[], int num_messages, int semaphore_magic_key)
 Access a named, custom whiteboard. More...
 
gu_simple_whiteboard_descriptorgswr_new_whiteboard (int i)
 access a remote named whiteboard: this is the designated constructore for C programs More...
 
gu_simple_whiteboard_descriptorgsw_new_numbered_whiteboard (const char *name, int num)
 access a named whiteboard: this is the designated standard wb constructor for C programs that want to assign a whiteboard number (uses a different semaphore than the default) More...
 
void gsw_free_whiteboard (gu_simple_whiteboard_descriptor *wbd)
 free the given whiteboard descriptor More...
 
int gsw_register_message_type (gu_simple_whiteboard_descriptor *wbd, const char *name)
 register a new whiteboard message type More...
 
int gsw_offset_for_message_type (gu_simple_whiteboard_descriptor *wbd, const char *name)
 get the numerical index of a whiteboard message type More...
 
gu_simple_whiteboardgsw_create (const char *name, int *fdp, bool *ini)
 create a simple whiteboard More...
 
gu_simple_whiteboard_descriptorget_local_singleton_whiteboard (void)
 create a simple whiteboard for the local singleton wb pointer More...
 
void gsw_free (gu_simple_whiteboard *wb, int fd)
 free the whiteboard More...
 
gsw_sema_t gsw_setup_semaphores (int key)
 set up a semaphore array for the whiteboard More...
 
int gsw_procure (gsw_sema_t sem, enum gsw_semaphores s)
 grab a whiteboard semaphore More...
 
int gsw_vacate (gsw_sema_t sem, enum gsw_semaphores s)
 release a whiteboard semaphore More...
 
void gsw_init_semaphores (gsw_sema_t sem)
 initialise the whiteboard semaphores More...
 
gu_simple_messagegsw_current_message (gu_simple_whiteboard *wb, int i)
 get the current shared memory location for the given whiteboard message type i More...
 
gu_simple_messagegsw_next_message (gu_simple_whiteboard *wb, int i)
 get the next shared memory location for the given whiteboard message type i More...
 
void gsw_increment (gu_simple_whiteboard *wb, int i)
 get the next shared memory location for the given whiteboard message type i More...
 
void gsw_increment_event_counter (gu_simple_whiteboard *wb, int i)
 add to a messages event counter on the wb More...
 
void gsw_add_process (gu_simple_whiteboard_descriptor *wbd, const pid_t proc)
 subscribe a new process to receive signals More...
 
void gsw_add_wbd_signal_handler (gu_simple_whiteboard_descriptor *wbd)
 add subscription signal handler More...
 
void gsw_remove_wbd_signal_handler (gu_simple_whiteboard_descriptor *wbd)
 remove subscription signal handler More...
 
void gsw_remove_process (gu_simple_whiteboard_descriptor *wbd, const pid_t proc)
 remove process for subscription signalling More...
 
void gsw_signal_subscribers (gu_simple_whiteboard *wb)
 signal all subscribing processes More...
 

Variables

const char * gsw_global_whiteboard_name
 global whiteboard name More...
 
int num_types_defined
 allow whiteboard to use old functions for whiteboard initialisation and choose which messages and consts they get More...
 
const char ** WBTypes_stringValues
 allow whiteboard to use old functions for whiteboard initialisation and choose which messages and consts they get More...
 

Macro Definition Documentation

◆ __block [1/2]

#define __block   _xblock

Definition at line 96 of file gusimplewhiteboard.h.

◆ __block [2/2]

#define __block   __attribute__((__blocks__(byref)))

Definition at line 96 of file gusimplewhiteboard.h.

◆ __has_feature

#define __has_feature (   x)    0

Definition at line 99 of file gusimplewhiteboard.h.

◆ GSW_DEFAULT_ENV

#define GSW_DEFAULT_ENV   "WHITEBOARD_NAME"

environment variable containing the default whiteboard file name

Definition at line 159 of file gusimplewhiteboard.h.

◆ GSW_DEFAULT_NAME

#define GSW_DEFAULT_NAME   "guWhiteboard"

fallback default wb

Definition at line 162 of file gusimplewhiteboard.h.

◆ GSW_NON_RESERVED_MESSAGE_TYPES

#define GSW_NON_RESERVED_MESSAGE_TYPES   (GSW_TOTAL_MESSAGE_TYPES-GSW_NUM_RESERVED)

Definition at line 155 of file gusimplewhiteboard.h.

◆ GSW_NUM_RESERVED

#define GSW_NUM_RESERVED   (GSW_TOTAL_MESSAGE_TYPES/2)

Definition at line 152 of file gusimplewhiteboard.h.

◆ GSW_NUM_TYPES_DEFINED

#define GSW_NUM_TYPES_DEFINED   num_types_defined

allow whiteboard to use old functions for whiteboard initialisation and choose which messages and consts they get

Definition at line 335 of file gusimplewhiteboard.h.

◆ GSW_TOTAL_MESSAGE_TYPES

#define GSW_TOTAL_MESSAGE_TYPES   512

message types (max)

Definition at line 149 of file gusimplewhiteboard.h.

◆ GSW_TOTAL_PROCESSES

#define GSW_TOTAL_PROCESSES   256

maximum subscriber procs

Definition at line 154 of file gusimplewhiteboard.h.

◆ GSWR_BASE_NAME

#define GSWR_BASE_NAME   "guudpwhiteboard"

UDP whiteboard name.

Definition at line 165 of file gusimplewhiteboard.h.

◆ GU_SIMPLE_WHITEBOARD_BUFSIZE

#define GU_SIMPLE_WHITEBOARD_BUFSIZE   128

message len (max)

Definition at line 146 of file gusimplewhiteboard.h.

◆ GU_SIMPLE_WHITEBOARD_GENERATIONS

#define GU_SIMPLE_WHITEBOARD_GENERATIONS   4

lifespan (max)

Definition at line 143 of file gusimplewhiteboard.h.

◆ GU_SIMPLE_WHITEBOARD_VERSION

#define GU_SIMPLE_WHITEBOARD_VERSION   6

version

Definition at line 141 of file gusimplewhiteboard.h.

◆ u_int16_t

#define u_int16_t   uint16_t

Definition at line 123 of file gusimplewhiteboard.h.

◆ u_int32_t

#define u_int32_t   uint32_t

Definition at line 120 of file gusimplewhiteboard.h.

◆ u_int64_t

#define u_int64_t   uint64_t

Definition at line 117 of file gusimplewhiteboard.h.

◆ u_int8_t

#define u_int8_t   uint8_t

Definition at line 126 of file gusimplewhiteboard.h.

◆ WHITEBOARD_POLL_PERIOD

#define WHITEBOARD_POLL_PERIOD   10000

Definition at line 171 of file gusimplewhiteboard.h.

◆ WHITEBOARD_SIGNAL

#define WHITEBOARD_SIGNAL   SIGUSR2

Definition at line 168 of file gusimplewhiteboard.h.

Typedef Documentation

◆ gsw_sema_t

typedef int gsw_sema_t

Definition at line 305 of file gusimplewhiteboard.h.

◆ gsw_subscription_f

typedef void(* gsw_subscription_f) (struct gsw_whiteboard_s *wbd)

Definition at line 185 of file gusimplewhiteboard.h.

◆ gu_simple_message

union type that is used to store data in shared memory

◆ gu_simple_whiteboard

the actual whiteboard in shared mem

◆ gu_simple_whiteboard_descriptor

the underlying whiteboard object

Enumeration Type Documentation

◆ gsw_semaphores

Enumerator
GSW_SEM_PUTMSG 

semaphore for adding to the whiteboard

GSW_SEM_CALLBACK 

semaphore for callback data

GSW_SEM_MSGTYPE 

semaphore for message type registration

GSW_SEM_PROC 

semaphore for process registration

GSW_NUM_SEM 

number of semaphores

Definition at line 174 of file gusimplewhiteboard.h.

Function Documentation

◆ get_local_singleton_whiteboard()

gu_simple_whiteboard_descriptor * get_local_singleton_whiteboard ( void  )

create a simple whiteboard for the local singleton wb pointer

Definition at line 281 of file gusimplewhiteboard.c.

Referenced by whiteboard_watcher::whiteboard_watcher(), generic_whiteboard_object< object_type >::init(), and SimpleWhiteboardTestPlainC::setUp.

◆ gsw_add_process()

void gsw_add_process ( gu_simple_whiteboard_descriptor wbd,
const pid_t  proc 
)

subscribe a new process to receive signals

add process for subscription signalling

subscribe a new process to receive signals

Definition at line 528 of file gusimplewhiteboard.c.

References gsw_procure(), GSW_SEM_PROC, GSW_TOTAL_PROCESSES, gsw_vacate(), gsw_simple_whiteboard_s::processes, gsw_whiteboard_s::sem, gsw_simple_whiteboard_s::subscribed, u_int16_t, and gsw_whiteboard_s::wb.

Referenced by whiteboard_watcher::subscribe(), and guWhiteboard::Whiteboard::subscribeToMessage().

◆ gsw_add_wbd_signal_handler()

void gsw_add_wbd_signal_handler ( gu_simple_whiteboard_descriptor wbd)

add subscription signal handler

Definition at line 613 of file gusimplewhiteboard.c.

References gsw_procure(), GSW_SEM_PROC, and gsw_whiteboard_s::sem.

Referenced by whiteboard_watcher::subscribe(), and guWhiteboard::Whiteboard::subscribeToMessage().

◆ gsw_create()

gu_simple_whiteboard * gsw_create ( const char *  name,
int *  fdp,
bool *  ini 
)

create a simple whiteboard

Parameters
namename of the whiteboard
fdppointer to internal file descriptor storage (NULL if not needed)
inipointer to boolean recording wb initialisation

Definition at line 296 of file gusimplewhiteboard.c.

References GSW_DEFAULT_NAME, gsw_free(), GU_SIMPLE_WHITEBOARD_BUFSIZE, GU_SIMPLE_WHITEBOARD_VERSION, gsw_simple_whiteboard_s::magic, gsw_simple_whiteboard_s::version, and WHITEBOARD_MAGIC.

Referenced by gsw_new_custom_whiteboard().

◆ gsw_current_message()

gu_simple_message * gsw_current_message ( gu_simple_whiteboard wb,
int  i 
)

get the current shared memory location for the given whiteboard message type i

Definition at line 498 of file gusimplewhiteboard.c.

References GU_SIMPLE_WHITEBOARD_GENERATIONS, gsw_simple_whiteboard_s::indexes, gsw_simple_whiteboard_s::messages, and u_int8_t.

Referenced by generic_whiteboard_object< object_type >::get(), and guWhiteboard::Whiteboard::getMessage().

◆ gsw_free()

void gsw_free ( gu_simple_whiteboard wb,
int  fd 
)

free the whiteboard

Parameters
wbwhiteboard to free
fdfile descriptor to close (-1 to skip)

Definition at line 351 of file gusimplewhiteboard.c.

Referenced by gsw_create().

◆ gsw_free_whiteboard()

void gsw_free_whiteboard ( gu_simple_whiteboard_descriptor wbd)

free the given whiteboard descriptor

Parameters
wbddescriptor for the whiteboard

Definition at line 254 of file gusimplewhiteboard.c.

Referenced by guWhiteboard::Whiteboard::~Whiteboard(), whiteboard_watcher::~whiteboard_watcher(), and gsw_new_custom_whiteboard().

◆ gsw_increment()

void gsw_increment ( gu_simple_whiteboard wb,
int  i 
)

get the next shared memory location for the given whiteboard message type i

Definition at line 514 of file gusimplewhiteboard.c.

References GU_SIMPLE_WHITEBOARD_GENERATIONS, gsw_simple_whiteboard_s::indexes, and u_int8_t.

Referenced by guWhiteboard::Whiteboard::addMessage(), and generic_whiteboard_object< object_type >::set().

◆ gsw_increment_event_counter()

void gsw_increment_event_counter ( gu_simple_whiteboard wb,
int  i 
)

add to a messages event counter on the wb

Definition at line 521 of file gusimplewhiteboard.c.

References gsw_simple_whiteboard_s::event_counters.

Referenced by guWhiteboard::Whiteboard::addMessage(), and generic_whiteboard_object< object_type >::set().

◆ gsw_init_semaphores()

void gsw_init_semaphores ( gsw_sema_t  sem)

initialise the whiteboard semaphores

Parameters
semwhiteboard semaphore descriptor

Definition at line 136 of file gusimplewhiteboard.c.

References GSW_NUM_SEM.

Referenced by gsw_new_custom_whiteboard(), and gsw_setup_semaphores().

◆ gsw_new_custom_whiteboard()

gu_simple_whiteboard_descriptor * gsw_new_custom_whiteboard ( const char *  name,
const char *  message_names[],
int  num_messages,
int  semaphore_magic_key 
)

Access a named, custom whiteboard.

This is the designated custom wb constructor for C programs

Parameters
nameThe name of the whiteboard to create/access
message_namesArray of char * containing the pre-defined (static) message names
num_messagesNumber of messages in the message_names array
semaphore_magic_keySemaphore magic key to use

Definition at line 206 of file gusimplewhiteboard.c.

References gsw_whiteboard_s::callback_queue, gsw_whiteboard_s::fd, gsw_create(), gsw_free_whiteboard(), gsw_init_semaphores(), gsw_register_message_type(), gsw_setup_semaphores(), gsw_whiteboard_s::sem, SEM_ERROR, and gsw_whiteboard_s::wb.

Referenced by gsw_new_numbered_whiteboard().

◆ gsw_new_numbered_whiteboard()

gu_simple_whiteboard_descriptor * gsw_new_numbered_whiteboard ( const char *  name,
int  num 
)

access a named whiteboard: this is the designated standard wb constructor for C programs that want to assign a whiteboard number (uses a different semaphore than the default)

Parameters
namename of the whiteboard
numwhiteboard number (0 for local, default whiteboard)

Definition at line 181 of file gusimplewhiteboard.c.

References gsw_new_custom_whiteboard(), GSW_NUM_RESERVED, GSW_NUM_TYPES_DEFINED, gsw_register_message_type(), SEMAPHORE_MAGIC_KEY, and WBTypes_stringValues.

Referenced by guWhiteboard::Whiteboard::Whiteboard(), gsw_new_whiteboard(), and gswr_new_whiteboard().

◆ gsw_new_whiteboard()

gu_simple_whiteboard_descriptor * gsw_new_whiteboard ( const char *  name)

access a named whiteboard: this is the designated constructore for C programs

Parameters
namename of the whiteboard

Definition at line 248 of file gusimplewhiteboard.c.

References gsw_new_numbered_whiteboard().

◆ gsw_next_message()

gu_simple_message * gsw_next_message ( gu_simple_whiteboard wb,
int  i 
)

get the next shared memory location for the given whiteboard message type i

Definition at line 506 of file gusimplewhiteboard.c.

References GU_SIMPLE_WHITEBOARD_GENERATIONS, gsw_simple_whiteboard_s::indexes, gsw_simple_whiteboard_s::messages, and u_int8_t.

Referenced by guWhiteboard::Whiteboard::addMessage(), and generic_whiteboard_object< object_type >::set().

◆ gsw_offset_for_message_type()

int gsw_offset_for_message_type ( gu_simple_whiteboard_descriptor wbd,
const char *  name 
)

get the numerical index of a whiteboard message type

Parameters
wbddescriptor for the whiteboard
namestring to use for identification
Returns
numerical identifier to use

Definition at line 476 of file gusimplewhiteboard.c.

References gsw_whiteboard_s::wb.

◆ gsw_procure()

◆ gsw_register_message_type()

int gsw_register_message_type ( gu_simple_whiteboard_descriptor wbd,
const char *  name 
)

register a new whiteboard message type

Parameters
wbddescriptor for the whiteboard
namestring to use for identification
Returns
numerical identifier to use

Definition at line 432 of file gusimplewhiteboard.c.

References gsw_procure(), GSW_SEM_MSGTYPE, gsw_whiteboard_s::sem, and gsw_whiteboard_s::wb.

Referenced by gsw_new_custom_whiteboard(), and gsw_new_numbered_whiteboard().

◆ gsw_remove_process()

◆ gsw_remove_wbd_signal_handler()

void gsw_remove_wbd_signal_handler ( gu_simple_whiteboard_descriptor wbd)

remove subscription signal handler

Definition at line 630 of file gusimplewhiteboard.c.

References gsw_whiteboard_s::exit_monitor, gsw_whiteboard_s::got_monitor, and WHITEBOARD_POLL_PERIOD.

◆ gsw_setup_semaphores()

gsw_sema_t gsw_setup_semaphores ( int  key)

set up a semaphore array for the whiteboard

Parameters
keysemaphore key
Returns
semaphore array to use

Definition at line 160 of file gusimplewhiteboard.c.

References gsw_init_semaphores(), GSW_NUM_SEM, SEM_A, SEM_ERROR, and SEM_R.

Referenced by gsw_new_custom_whiteboard().

◆ gsw_signal_subscribers()

◆ gsw_vacate()

◆ gswr_new_whiteboard()

gu_simple_whiteboard_descriptor * gswr_new_whiteboard ( int  i)

access a remote named whiteboard: this is the designated constructore for C programs

Parameters
imachine id of the remote whiteboard

Definition at line 241 of file gusimplewhiteboard.c.

References gsw_new_numbered_whiteboard(), and GSWR_BASE_NAME.

Variable Documentation

◆ gsw_global_whiteboard_name

const char* gsw_global_whiteboard_name
extern

global whiteboard name

Definition at line 78 of file Whiteboard.cc.

Referenced by guWhiteboard::Whiteboard::Whiteboard().

◆ num_types_defined

int num_types_defined
extern

allow whiteboard to use old functions for whiteboard initialisation and choose which messages and consts they get

◆ WBTypes_stringValues

const char** WBTypes_stringValues
extern

allow whiteboard to use old functions for whiteboard initialisation and choose which messages and consts they get

Referenced by gsw_new_numbered_whiteboard().