bpo_queue - Message Queue Routines

The bpo_queue module provides the mechanisms for queueing messages between processes, and for rendevousing on a queue for a message.

    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:

void *hint

A hint pointer for which segment to use.

char *q_name

The name the queue should be known by.

int q_max

Specifies the maximum number of items that are allowed on the queue.

int q_flags

The flags parameter can be one of two values.

Q_SOLE_READER This will be the only process reading from this queue.
Q_MULTI_READ This process may be one of many that will read from the queue.
Q_PERSISTENT This flag can be used in conjunction with the Q_SOLE_READER flag to ensure that the queue is not removed on a cleanup operation when there is not current reader.

int q_mech

This specifies what form of notification should be used when an item is placed on the queue. It currently may be one of two values.

Q_NM_NONE No action should be taken when an item is added.
Q_NM_PIPE This causes the Inform_Process_Pid routine to be called for each attached process whenever a message is placed on the queue.

The routine either returns a pointer to the queue structure, or NULL if there is any problem. The routine may fail for a number of reasons, these include;

Invalid hint.
Segment does not support queues.
Unable to allocate queue resource.
Queue already exists and is Q_SOLE_READER by another live process.
Unable to allcoate space for queue structure.

Note that it is possible for a process to take over a existing Q_SOLE_READER queue structure if the process that created it is no longer running.

    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.

The following functions deal with a higher layer abstraction, a queue message. This structure

    struct bpo_Q_Mesg
    {
    bpo_Node_t      Q_Node;         /* Node for linking to Q */
    int	            Q_Reply_id;     /* id of reply Q */
    };

contains a node for linking the item into a queue, and an id of 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 Q

The 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 an id of the reply queue.

The mpReplyMsg function takes the reply queue id, searches the queue list for the required queue and sends the message to the queue.

    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.