struct bpo_Q * mpCreateQ( const void *hint, const char *q_name, int q_max, int q_flags, int q_mech );The mpCreateQ routine allows for the creation of a queue, and how the queue should react when messages are placed on it. This routine should also be called when the queue already exists as a multiple reader and your process wishes to be registered as a reader.
The parameters are as follows:
int mpPutMsg( const char *q_name, bpo_Node_t *q_node );This function attaches the node to the queue in question. The function function returns -1 on a serious error (queue does not exist, queue has been deleted, etc), 0 if the queue is full and 1 if the message was added successfully.
void *mpGetMsg( const char *q_name, const void *hint );This function attempts to remove an item from the named queue. If the function succeeds the value returned will be a pointer to whatever type of structure was pointed to when the queue node was initialised. If there is a problem (queue does not exist, nothing on the queue) then the function returns NULL.
struct bpo_Q_Mesg { bpo_Node_t Q_Node; /* Node for linking to Q */ off_t reply_Q; /* offset to reply Q */ };contains a node for linking the item into a queue, and an offset to a queue which should exist, and where the message should be sent after it has been processed.
The usual operation of these functions would be as follows
Process One Process Two Create reply queue Create work Q Create item with Q_mesg Wait on work Q Post to work Q (with reply Q) GetMsg from work Q Wait Reply Q process message Reply message Get message from reply QThe two functions are:
int mpPostMsg( const char *q_name, struct bpo_Q_Mesg *mesp, struct bpo_Q *reply_q ); int mpReplyMsg( struct bpo_Q_Mesg *mesp );As is apparent, the mpPostMsg routine, takes a name parameter specifying the queue to attach the node to, a pointer to the bpo_Q_Mesg structure containing the node to be linked, and a pointer to the reply queue.
The mpReplyMsg function simply takes a pointer a bpo_Q_Mesg structure which will already have the queue to return to set by the originator's mpPostMsg call.
void *mpFindQ( const char *q_name, const void *hint );This function returns a pointer to the requested queue if it exists, or NULL if it does not.
int mpCheckQ( const char *q_name, const void *hint );This function returns that number of items on the queue, or -1 if the queue cannot be found.
int mpWaitQ( const char *name, const void *hint );The mpWaitQ function waits on the named queue until there is either a message on the queue, or the process is signalled. The function returns the number of items on the queue or -1 if the queue could not be found.
void *bpo_send_and_get( const char *q_name, struct bpo_Q_Mesg *bpo_msg, struct bpo_Q *reply_q );The bpo_send_and_get function provides a convenient wrapper around a
mpPostMsg(); mpWaitQ(); mpGetMsg();sequence together with suitable error trapping.