msq_util - Message Queue Utilities

The MSQ utilities provide a high-level interface to the underlying operating system's message queue facility.

Creating a message queue (or accessing an existing message queue) is as simple as this:

    #include  "msq_util.h"			-- Message queue utilities.
    MessageQueue  queue ;
    ...
    msqOpen ("name", &queue) ;
    ...

Reading messages from and writing messages to a message queue are equally simple, as shown in this loopback example:

    char  buffer[MAX_SIZE] ;
    int  length ;
    ...
    sprintf (buffer, "Hello!") ;		-- Send a message.
    msqWrite (queue, -1.0, buffer, -1) ;
    ...						-- Read the message.
    msqRead (queue, -1.0, sizeof buffer, buffer, &length) ;
    ...

Timeouts can be specified so that msqRead() or msqWrite() will return if the timeout interval expires without the intended operation completing. In the examples above, a timeout of -1.0 causes the calling process to wait as long as is necessary to read from or write to the queue.

When a message queue is no longer needed by a process, it should be deleted:

    msqClose (queue) ;

The message queue isn't actually deleted from the system until the last process using it deletes it.

Implementation Notes (UNIX)

The UNIX message queue functions, msgget(2) et al, are used to create and access message queues. The name/IPC identifier mappings and reference counts are stored in the named object database (see nob_util.c).

Timeouts in msqRead() and msqWrite() are implemented by polling the queue every second to see if it is ready for reading or writing. Consequently, timeout intervals have a one-second resolution under UNIX; fractions of seconds are essentially truncated.

Processes should delete all message queues before exiting; if a process exits prematurely, the named object database could be left in an inconsistent state.

Implementation Notes (VxWorks)

Under VxMP, the message queues are accessible on other CPUs (see msgQSmLib(1)). The name/identifier mappings and reference counts are stored in the named object database (see nob_util.c).

Timeouts in the msqRead() call are supported. Note that the timeout error code returned by the VxWorks system call is converted into an EWOULDBLOCK error code.

Processes should delete all message queues before exiting; if a process exits prematurely, the named object database could be left in an inconsistent state.

Public Procedures

msqClose() - deletes a message queue.

msqId() - returns the IPC identifier for a message queue.

msqOpen() - creates a message queue.

msqPoll() - returns the number of messages waiting to be read from a queue.

msqRead() - reads the next message from a message queue.

msqWrite() - writes a message to a message queue.

Source Files

msq_util.c

msq_util.h