TSP: The Transport Sample Protocol



Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

BlackBoard
[TSP_Utils]

BlackBoard idiom definition and functions. More...


Modules

SimpleBlackBoard
BBUtils
BBTools
 BB Tools are a set of TSP BlackBoard tools use to interact (locally) with any TSP BlackBoard.


Data Structures

struct  S_BB
 BlackBoard definition. More...

struct  S_BB_DATADESC
 BlackBoard data descriptor. More...

struct  S_BB_MSG
 BlackBoard message definition. More...


Typedefs

typedef S_BB_DATADESC S_BB_DATADESC_T
 BlackBoard data descriptor.

typedef S_BB_MSG S_BB_MSG_T
 BlackBoard message definition.

typedef S_BB S_BB_T
 BlackBoard definition.


Enumerations

enum  E_BB_TYPE_T
 BlackBoard publishable data type. More...


Functions

int GLU_set_base_frequency (double d_frequence_provider)
 Indique la frequence de base du provider TSP.

int32_t bb_tsp_provider_initialise (int *argc, char **argv[], int TSPRunMode, const char *bbname)
 Initialisation du fournisseur de donnée TSP pour un BlackBoard TSP.

int32_t bb_size (const int32_t n_data, const int32_t data_size)
 Return the size of a blackboard with n_data publishable elements with a data zone of size data_size byte.

int32_t bb_find (volatile S_BB_T *bb, const char *var_name)
 Search a variable within a BlackBoard.

S_BB_DATADESC_Tbb_data_desc (volatile S_BB_T *bb)
 Return a pointer to the beginning of the data descriptor array of the specified BB.

void * bb_data (volatile S_BB_T *bb)
 Return a pointer to the beginning of the data array of the specified BB.

double bb_double_of (void *value, E_BB_TYPE_T bbtype)
 Return a double value from the pointer value considered as the bbtype.

int32_t bb_data_initialise (volatile S_BB_T *bb, S_BB_DATADESC_T *data_desc, void *default_value)
 Initialise a freshly created structure to a default value.

int32_t bb_data_print (volatile S_BB_T *bb, S_BB_DATADESC_T data_desc, FILE *pf)
 Print the content of a data descriptor.

int32_t bb_create (S_BB_T **bb, const char *pc_bb_name, int n_data, int data_size)
 Create a blackboard.

int32_t bb_destroy (S_BB_T **bb)
 Destroy a blackboard.

int32_t bb_lock (volatile S_BB_T *bb)
 Lock blackboard.

int32_t bb_unlock (volatile S_BB_T *bb)
 Unlock blackboard.

int32_t bb_attach (S_BB_T **bb, const char *bb_name)
 Attach to an existing blackboard.=.

int32_t bb_detach (S_BB_T **bb)
 Detach from blackboard.

void * bb_publish (volatile S_BB_T *bb, S_BB_DATADESC_T *data_desc)
 Publish a data in a blackboard.

void * bb_subscribe (volatile S_BB_T *bb, S_BB_DATADESC_T *data_desc)
 Subscribe to blackboard data.

int32_t bb_dump (volatile S_BB_T *bb, FILE *filedesc)
 Dump a blackboard to a file stream.

int bb_get_nb_max_item (volatile S_BB_T *bb)
 Return the maximum number of data that could be published in blackboard.

int bb_get_nb_item (volatile S_BB_T *bb)
 Return the number of data that are currently published in blackboard.

int bb_get_mem_size (volatile S_BB_T *bb)
 Return the memory occupation (in byte) of a blackboard.

int32_t bb_shadow_get (S_BB_T *bb_shadow, volatile S_BB_T *bb_src)
 Ask for a shadow blackboard creation.

int32_t bb_shadow_update_data (S_BB_T *bb_shadow, volatile S_BB_T *bb_src)
 Update the data zone of a shadow blackboard.

int32_t bb_msg_id (volatile S_BB_T *bb)
 Return the BB message queue identifier.

int32_t bb_snd_msg (volatile S_BB_T *bb, S_BB_MSG_T *msg)
 Send message through BB msg queue.

int32_t bb_rcv_msg (volatile S_BB_T *bb, S_BB_MSG_T *msg)
 Receive a message on the BB message queue.


Detailed Description

BlackBoard idiom definition and functions.

A blackboard is an inter-process communication mean based on the publish/subscribe principle. Every process/thread attached to the blackboard may publish or subscribe to a piece of data using a key (string based in this implementation).


Typedef Documentation

typedef struct S_BB_DATADESC S_BB_DATADESC_T
 

BlackBoard data descriptor.

Referenced by bb_data_desc(), bb_data_initialise(), bb_data_print(), bb_publish(), bb_simple_publish(), bb_simple_subscribe(), bb_size(), and bb_subscribe().

typedef struct S_BB_MSG S_BB_MSG_T
 

BlackBoard message definition.

This type must conform to the constraint of a SysV message queue message used by msgsnd(2).

Referenced by bb_rcv_msg(), bb_simple_synchro_go(), bb_simple_synchro_wait(), and bb_snd_msg().

typedef struct S_BB S_BB_T
 

BlackBoard definition.

A blackboard implements the publish/subsbcribe idiom.

Referenced by bb_attach(), bb_data(), bb_data_desc(), bb_data_initialise(), bb_data_print(), bb_destroy(), bb_detach(), bb_dump(), bb_find(), bb_get_mem_size(), bb_get_nb_item(), bb_get_nb_max_item(), bb_lock(), bb_msg_id(), bb_publish(), bb_rcv_msg(), bb_shadow_get(), bb_shadow_update_data(), bb_simple_publish(), bb_simple_subscribe(), bb_simple_synchro_go(), bb_simple_synchro_verify(), bb_simple_synchro_wait(), bb_size(), bb_snd_msg(), bb_subscribe(), and bb_unlock().


Enumeration Type Documentation

enum E_BB_TYPE_T
 

BlackBoard publishable data type.

Definition at line 89 of file bb_core.h.

Referenced by GLU_init().


Function Documentation

int32_t bb_attach S_BB_T **  bb,
const char *  bb_name
 

Attach to an existing blackboard.=.

Parameters:
bb OUT, Pointer to BB pointer (should not be NULL). the pointed value is updated is BB attach succeed.
bb_name IN, blackboard name
Returns:
E_OK if blackboard exists and attach succeed E_NOK otherwise.

Definition at line 646 of file bb_core.c.

References bb_logMsg(), bb_utils_build_shm_name(), bb_utils_ntok(), and S_BB_T.

Referenced by GLU_init().

int32_t bb_create S_BB_T **  bb,
const char *  pc_bb_name,
int  n_data,
int  data_size
 

Create a blackboard.

Create a shared memory segment of the specified size then mmap it for the current process and initialize the zone to contains a fresh new blackboard structure. Only one process should create a blackboard others should attach through

See also:
bb_attach(S_BB_T**, const char*).
Parameters:
bb INOUT Pointer to a BB pointer. IN, non NULL pointer. OUT, the pointed element is the new created BB or NULL is creation failed.
pc_bb_name IN, the blackboard name
n_data IN maximum data to be stored in blackboard. I.e. the number of different published element in BB (each element has an associated key)
data_size IN the maximum data zone size (in byte) of the blackboard. This is the sum of all data published in the blackboard.
Returns:
E_OK if creation succeed E_NOK if failed.

void* bb_data volatile S_BB_T bb  ) 
 

Return a pointer to the beginning of the data array of the specified BB.

Parameters:
bb IN BlackBoard pointer
Returns:
start address of the data array in bb

Definition at line 119 of file bb_core.c.

References S_BB_T.

Referenced by bb_data_initialise(), bb_dump(), bb_publish(), bb_shadow_update_data(), bb_subscribe(), and GLU_init().

S_BB_DATADESC_T* bb_data_desc volatile S_BB_T bb  ) 
 

Return a pointer to the beginning of the data descriptor array of the specified BB.

Parameters:
bb IN BlackBoard pointer
Returns:
start address of the data descriptor array in bb

Definition at line 107 of file bb_core.c.

References S_BB_DATADESC_T, and S_BB_T.

Referenced by bb_dump(), bb_find(), bb_publish(), bb_subscribe(), and GLU_init().

int32_t bb_data_initialise volatile S_BB_T bb,
S_BB_DATADESC_T data_desc,
void *  default_value
 

Initialise a freshly created structure to a default value.

If default value pointer is NULL then all type are initialized to 0 but the E_BB_USER for which the data zone is set to binary 0.

Parameters:
bb IN pointer to the blackboard whose the data belongs.
data_desc INOUT pointer to the data descriptor structure (should NOT be NULL).
default_value INOUT default pointer to the default value used for init. If NULL then initialize to 0.
Returns:
E_OK if init OK E_NOK otherwise.

Definition at line 183 of file bb_core.c.

References bb_data(), S_BB_DATADESC::data_offset, S_BB_DATADESC::dimension, S_BB_DATADESC_T, S_BB_T, and S_BB_DATADESC::type.

Referenced by bb_publish().

int32_t bb_data_print volatile S_BB_T bb,
S_BB_DATADESC_T  data_desc,
FILE *  pf
 

Print the content of a data descriptor.

Parameters:
bb IN pointer to BB where the data reside
data_desc INOUT pointer to data descriptor.
pf INOUT stream file pointer to be used for printing.
Returns:
always return E_OK unless pf is NULL.

Definition at line 393 of file bb_core.c.

References S_BB_DATADESC_T, and S_BB_T.

Referenced by bb_dump().

int32_t bb_destroy S_BB_T **  bb  ) 
 

Destroy a blackboard.

Destroy the BB structure. Destroy the shared memory segment and detach from it. Note that effective shared memory segment destruction will occur when the last process attached is detached (through

See also:
bb_detach for example).
Parameters:
bb INOUT Pointer to BB pointer. Should not be NULL.
Returns:
E_OK on success E_NOK otherwise.

Definition at line 532 of file bb_core.c.

References bb_logMsg(), bb_utils_build_shm_name(), bb_utils_ntok(), and S_BB_T.

int32_t bb_detach S_BB_T **  bb  ) 
 

Detach from blackboard.

Parameters:
bb INOUT, Pointer to BB pointer (should not be NULL)
Returns:
E_OK if blackboard exists and detach succeed E_NOK otherwise.

Definition at line 690 of file bb_core.c.

References bb_logMsg(), and S_BB_T.

double bb_double_of void *  value,
E_BB_TYPE_T  bbtype
 

Return a double value from the pointer value considered as the bbtype.

Parameters:
value IN pointer to the value
bbtype IN the type of the pointer
Returns:
double value of the pointed value

Definition at line 131 of file bb_core.c.

int32_t bb_dump volatile S_BB_T bb,
FILE *  filedesc
 

Dump a blackboard to a file stream.

Blackboard description and all data content is dumped.

Parameters:
bb INOUT, pointer to BB.
filedesc INOUT, file stream descriptor.
Returns:
E_OK if dump succeed E_NOK otherwise.

Definition at line 797 of file bb_core.c.

References bb_data(), bb_data_desc(), bb_data_print(), and S_BB_T.

int32_t bb_find volatile S_BB_T bb,
const char *  var_name
 

Search a variable within a BlackBoard.

Parameters:
bb IN BlackBoard pointer
var_name IN the name of the searched variable
Returns:
index of the variable in the BB descriptor array

Definition at line 89 of file bb_core.c.

References bb_data_desc(), and S_BB_T.

Referenced by bb_publish(), and bb_subscribe().

int bb_get_mem_size volatile S_BB_T bb  ) 
 

Return the memory occupation (in byte) of a blackboard.

Parameters:
bb IN, pointer to BB.
Returns:
memory occupied by the specified BB in bytes

Definition at line 860 of file bb_core.c.

References bb_size(), and S_BB_T.

Referenced by bb_shadow_get(), and GLU_init().

int bb_get_nb_item volatile S_BB_T bb  ) 
 

Return the number of data that are currently published in blackboard.

Parameters:
bb IN, pointer to blackboard.
Returns:
the number of data currently published in blackboard.

Definition at line 845 of file bb_core.c.

References S_BB_T.

Referenced by GLU_init().

int bb_get_nb_max_item volatile S_BB_T bb  ) 
 

Return the maximum number of data that could be published in blackboard.

Parameters:
bb IN, pointer to blackboard.
Returns:
the maximum number of data that could be published in blackboard

Definition at line 831 of file bb_core.c.

References S_BB_T.

int32_t bb_lock volatile S_BB_T bb  ) 
 

Lock blackboard.

A BlackBoard should be locked befaore any structural change or to protect different process against each other from concurrent modifications. This is a blocking call (using sys V semaphore).

See also:
bb_publish/

bb_subscribe automatically lock the blackboard.

Parameters:
bb INOUT BB pointer, should not be NULL.
Returns:
E_OK if lock succeed, E_NOK otherwise.

Definition at line 590 of file bb_core.c.

References bb_logMsg(), and S_BB_T.

Referenced by bb_publish(), bb_shadow_get(), bb_shadow_update_data(), and bb_subscribe().

int32_t bb_msg_id volatile S_BB_T bb  ) 
 

Return the BB message queue identifier.

Parameters:
bb INOUT, pointer to BB.
Returns:
message queue id

Definition at line 920 of file bb_core.c.

References S_BB_T.

Referenced by bb_simple_synchro_verify().

void* bb_publish volatile S_BB_T bb,
S_BB_DATADESC_T data_desc
 

Publish a data in a blackboard.

This request allocate space for the specified data in blackboard and return the address of the newly allocated space. This function has the same semantic as malloc(3).

Parameters:
bb INOUT, BB pointer (should not be NULL).
data_desc INOUT, Data descriptor of the data to be published. OUT, if data has been properly allocated the S_BB_DATADESC_T.data_offset is updated.
Returns:
address of the allocated data, NULL if allocation failed.

Definition at line 714 of file bb_core.c.

References bb_data(), bb_data_desc(), bb_data_initialise(), bb_find(), bb_lock(), bb_logMsg(), bb_subscribe(), bb_unlock(), S_BB_DATADESC::data_offset, S_BB_DATADESC::dimension, S_BB_DATADESC::name, S_BB_DATADESC_T, S_BB_T, and S_BB_DATADESC::type_size.

Referenced by bb_simple_publish().

int32_t bb_rcv_msg volatile S_BB_T bb,
S_BB_MSG_T msg
 

Receive a message on the BB message queue.

This is a blocking call.

Parameters:
bb INOUT, pointer to BB.
msg INOUT, the message to be read. The type of the message to be received should be be specified on entry in the message structure msg->mtype.
Returns:
E_OK on success, E_NOK otherwise

Definition at line 972 of file bb_core.c.

References bb_logMsg(), S_BB_MSG::mtype, S_BB_MSG_T, and S_BB_T.

Referenced by bb_simple_synchro_wait().

int32_t bb_shadow_get S_BB_T bb_shadow,
volatile S_BB_T bb_src
 

Ask for a shadow blackboard creation.

A shadow blackboard is a blackboard which does not reside in shared memory is meant to be in local memory. This BB is not meant to be shared between several process or thread. The only valid operation on a shadow BB are:

  • bb_shadow_get,
  • bb_shadow_update_data
  • direct access to BB data This kind of BB is used for flip/flop BB distribution with a blackboard TSP provider.
    Parameters:
    bb_shadow INOUT, pointer to pre-allocated data zone which will receive the shadow BB.
    bb_src IN, pointer to source blackboard to be shadowed.
    Returns:
    E_OK on success E_NOK if not.

Definition at line 876 of file bb_core.c.

References bb_get_mem_size(), bb_lock(), bb_unlock(), S_BB_T, and S_BB::semid.

Referenced by GLU_init().

int32_t bb_shadow_update_data S_BB_T bb_shadow,
volatile S_BB_T bb_src
 

Update the data zone of a shadow blackboard.

This is essentially a memcpy of the blackboard data zone.

Parameters:
bb_shadow INOUT, pointer to shadow BB
bb_src IN, pointer to source BB (the same BB initially used for making shadow)
Returns:
E_OK on success.

Definition at line 900 of file bb_core.c.

References bb_data(), bb_lock(), bb_unlock(), S_BB::data_free_offset, and S_BB_T.

Referenced by GLU_init().

int32_t bb_size const int32_t  n_data,
const int32_t  data_size
 

Return the size of a blackboard with n_data publishable elements with a data zone of size data_size byte.

Parameters:
n_data IN the number of publishable data in blackboard
data_size IN the size (in byte) of the blackboard data zone.
Returns:
the size (in byte) of this kind of blackboard.

Definition at line 77 of file bb_core.c.

References S_BB_DATADESC_T, and S_BB_T.

Referenced by bb_get_mem_size().

int32_t bb_snd_msg volatile S_BB_T bb,
S_BB_MSG_T msg
 

Send message through BB msg queue.

This is a non blocking call, if there is no more room in the message queue, the message is not sent and lost.

Parameters:
bb INOUT, pointer to BB
msg INOUT, pointer to message to be sent
Returns:
E_OK on success E_NOK otherwise.

Definition at line 930 of file bb_core.c.

References bb_logMsg(), S_BB_MSG_T, and S_BB_T.

Referenced by bb_simple_synchro_go().

void* bb_subscribe volatile S_BB_T bb,
S_BB_DATADESC_T data_desc
 

Subscribe to blackboard data.

The function search the data in BB and return its address if found.

Parameters:
bb IN, pointer to BB.
data_desc INOUT, data descriptor for the searched data on entry updated data desc if found.
Returns:
data address if found NULL if not found.

Definition at line 768 of file bb_core.c.

References bb_data(), bb_data_desc(), bb_find(), bb_lock(), bb_unlock(), S_BB_DATADESC::data_offset, S_BB_DATADESC::dimension, S_BB_DATADESC::name, S_BB_DATADESC_T, S_BB_T, S_BB_DATADESC::type, and S_BB_DATADESC::type_size.

Referenced by bb_publish(), and bb_simple_subscribe().

int32_t bb_tsp_provider_initialise int *  argc,
char **  argv[],
int  TSPRunMode,
const char *  bbname
 

Initialisation du fournisseur de donnée TSP pour un BlackBoard TSP.

On doit passer à cette fonction d'initialisation les argument en provenance d'un main car la lib TSP peut de cette manière gérer des paramètres spécifiques à TSP. Les paramètres qui ne concernent pas TSP seront inchangés.

Parameters:
argc Le parametre argc d'un main avant que le main ne l'utilise.
argv Le parametre argc d'un main avant que le main ne l'utilise.
TSPRunMode mode de démarrage 0 = non bloquant, 1 = bloquant.
bbname le nom du blackboard auquel s'attacher
Returns:
E_OK si initialisation réalisée E_NOK sinon.

Definition at line 361 of file bb_tsp_provider.c.

References TSP_ASYNC_REQUEST_NON_BLOCKING, TSP_provider_init(), TSP_provider_rqh_manager_get_nb_running(), and TSP_provider_run().

int32_t bb_unlock volatile S_BB_T bb  ) 
 

Unlock blackboard.

Parameters:
bb INOUT, BB pointer, should not be NULL.
Returns:
E_OK if unlock succeed, E_NOK otherwise.

Definition at line 619 of file bb_core.c.

References bb_logMsg(), and S_BB_T.

Referenced by bb_publish(), bb_shadow_get(), bb_shadow_update_data(), and bb_subscribe().

int GLU_set_base_frequency double  d_frequence_provider  ) 
 

Indique la frequence de base du provider TSP.

Parameters:
d_frequence_provider la frequence de base en Hz
Returns:
toujours 0, cette fonction n'échoue jamais.

Definition at line 98 of file bb_tsp_provider.c.

Framework Home Page.


Beware !! TSP wave is coming...