A message queue is a System V IPC facility that sends raw data between processes on the same machine. The os_message_queue class is a thin wrapper around System V message queues. This class supports a raw interface for reading and writing messages. When a buffer is written, the first long of the buffer holds the message type. When a message is read, the first long of the buffer is filled with the message type.

When a message is received, the received type is cached internally and can be obtained using the last_type() message. By default, reading a message queue returns the first message in the input queue. You can request that only messages with a specific type are read by using read_type() , or that only messages with a type less than or equal to a specific type are read by using read_type_equal_or_less_than() . If an attempt is made to read a message longer than the buffer supplied, and the queue's I/O control includes the O_NOERROR flag, the message is silently truncated; otherwise, an E2BIG error is generated and the message remains on the queue.

Conversions permit interchangeable use of os_message_queue and os_vid_t (the System V IPC ID).

Legal open control:	`O_OPEN, O_CREAT, O_EXCL`
Legal I/O control:	`O_NONBLOCK, O_NOERROR`
Default I/O control:	`0` (blocking, error on read buffer overflow)

Interface

Constructor

os_message_queue( os_vid_t id )

Constructs an object to reference the existing message queue with ID id . Initializes to receive any message type using default I/O control (blocking and error on truncate).

Constructor

os_message_queue( const os_key& key , os_ioctl_t control )

Constructs an object to reference the existing message queue with key key and sets I/O control to control (default is blocking and error on truncate).

Throws: os_unix_toolkit_error

Constructor

os_message_queue( os_mode_t mode , os_ioctl_t control )

Constructs an object to reference a new message queue with a private key, mode mode , and I/O control control (default blocking and error on truncate).

Throws: os_unix_toolkit_error

Constructor

os_message_queue( const os_key& key , os_open_t open , os_mode_t mode , os_ioctl_t control )

Constructs an object to reference a new message queue with key key , open control flags open , mode mode , and I/O control control (default blocking and error on truncate). If a message queue with key key already exists, references the existing message queue and ignores the mode parameter.

Throws: os_unix_toolkit_error

bool operator<( const os_message_queue& queue ) const

Returns true if the ID is less than queue .

bool operator==( const os_message_queue& queue ) const

Returns true if the ID is the same as queue .

(os_vid_t)

operator os_vid_t() const

Returns the ID.

bytes_on_queue

int bytes_on_queue() const

Returns the number of bytes of data waiting in the queue.

Throws: os_unix_toolkit_error

clear

void clear()

Resets the state to good.

creator_group

os_gid_t creator_group() const

Returns the creator's group ID.

Throws: os_unix_toolkit_error

creator_user

os_uid_t creator_user() const

Returns the creator's user ID.

Throws: os_unix_toolkit_error

defined

bool defined() const

Returns true if the ID is not OS_UNDEFINED .

good

bool good() const

Returns true if the object is not in a failed state.

void id( os_vid_t id )

Sets the ID to id .

os_vid_t id() const

Returns the ID.

io_control

void io_control( os_ioctl_t control )

Sets the I/O control setting to control .

io_control

os_ioctl_t io_control() const

Returns the I/O control setting.

key

os_key key() const

Returns the key.

Throws: os_unix_toolkit_error

last_change_time

os_time_and_date last_change_time() const

Returns the time of the last queue state change.

Throws: os_unix_toolkit_error

last_receive_process

os_pid_t last_receive_process() const

Returns the process ID of the last process that received a message from the queue.

Throws: os_unix_toolkit_error

last_receive_time

os_time_and_date last_receive_time() const

Returns the time the last message was read from the queue.

Throws: os_unix_toolkit_error

last_send_process

os_pid_t last_send_process() const

Returns the process ID of the last process to send a message to the queue.

Throws: os_unix_toolkit_error

last_send_time

os_time_and_date last_send_time() const

Returns the time the last message was written to the queue.

Throws: os_unix_toolkit_error

last_type

long last_type() const

Returns the type of the last message received. If no messages have been received, returns OS_UNDEFINED .

max_bytes_on_queue

int max_bytes_on_queue() const

Returns the maximum number of bytes that can be waiting on the queue.

Throws: os_unix_toolkit_error

messages_on_queue

int messages_on_queue() const

Returns the number of messages waiting in the queue.

Throws: os_unix_toolkit_error

mode

os_mode_t mode() const

Returns the mode.

Throws: os_unix_toolkit_error

mode

void mode( os_mode_t mode )

Sets the mode to mode .

Throws: os_unix_toolkit_error

bool ok() const

Returns true if the object has not failed.

owner_group

os_gid_t owner_group() const

Returns the object owner's group ID.

Throws: os_unix_toolkit_error

owner_group

void owner_group( os_gid_t group )

Sets the object owner's group to group .

Throws: os_unix_toolkit_error

owner_user

os_uid_t owner_user() const

Returns the object owner's user ID.

Throws: os_unix_toolkit_error

owner_user

void owner_user( os_uid_t user )

Sets the object owner's user to user .

Throws: os_unix_toolkit_error

print

void print( ostream& stream ) const

Prints the ID to stream .

read

ssize_t read( void* buffer , size_t bytes )

Reads a raw message into buffer based on the current type filtering. See the read...() family of type filtering members to select the message filter. The first long of the buffer is filled with the message type. The remainder of the buffer is filled with a maximum of bytes bytes of data. Returns the number of bytes of data placed in buffer , not including the type.

Throws: os_unix_toolkit_error

read_any_type

void read_any_type()

Reads the next available message regardless of its type.

read_type

void read_type( long type )

Only reads messages of type type . The value of type must be positive.

read_type_equal_to_or_less_than

void read_type_equal_to_or_less_than( long type )

Only reads messages of type equal-to or less-than type . The value of type must be positive.

remove

void remove()

Immediately removes the message queue from the operating system. Any remaining data in the queue is lost. Any process still trying to access the queue fails.

Throws: os_unix_toolkit_error

slot_sequence_number

int slot_sequence_number() const

Returns the slot usage sequence number.

Throws: os_unix_toolkit_error

write

ssize_t write( const void* buffer , size_t bytes )

Writes a raw message from buffer . The first long in buffer is the message type. The parameter bytes is the number of bytes in buffer , not including the message type. Returns bytes on success.

Throws: os_unix_toolkit_error

message_queue

Library

Declaration

Options

Interface

Non-Member Functions