Arp::System::Commons::Ipc::MessageQueue Class Reference

Message queues allow processes to exchange data in form of messages More...

#include <MessageQueue.hpp>

Public Types
enum class	OpenMode { CreateNew = 0 , Open , OpenOrCreate }
	Supported opening modes for message queues. More...
enum class	Access { ReadOnly , WriteOnly , ReadWrite }
	Supported access modes for message queues. More...

Public Member Functions
	MessageQueue (const String &name, bool blocking=false)
	Tries to open an already existing message queue. More...
	MessageQueue (const String &name, OpenMode openMode, Access permission=Access::ReadWrite, bool blocking=false)
	Tries to construct a new message queue based on assigned parameters. More...
	MessageQueue (const String &name, OpenMode openMode, Access permission, bool blocking, long maxmsg, long msgsize)
	Tries to construct a new message queue based on assigned parameters. More...
	~MessageQueue (void)
	Destructs this instance and closes the message queue. More...
bool	IsBlocking () const
	Checks if this message queue was created in blocking mode. More...
long	GetMessageCount () const
	Queries the current amount of message stored in the message queue. More...
long	GetMaxMessageCount () const
	Queries the maximal amount of messages that can be stored inside the message queue. More...
long	GetMaxMessageSize () const
	Queries the maximal supported byte-size of a message. More...
void	Send (const char *pMsg, size_t len, unsigned int prio, Milliseconds timeoutMs=Milliseconds(0))
	Sends a message to the queue. More...
size_t	Receive (char *pBuffer, size_t len, unsigned int &prio, Milliseconds timeoutMs=Milliseconds(0))
	Receives a message from the queue. More...
void	Close ()
	Closes the message queue. More...
void	Unlink ()
	Deletes the message queue. More...

Detailed Description

Message queues allow processes to exchange data in form of messages

Message queues are identified by names of the form /somename, that is, each name must begin with a slash otherwise an exception will be thrown during invocation of the constructor.

Member Enumeration Documentation

Access

enum Arp::System::Commons::Ipc::MessageQueue::Access

strong

Supported access modes for message queues.

Enumerator
ReadOnly	Object owner has only permission for read access.
WriteOnly	Object owner has only permission for write access.
ReadWrite	Object owner can reas and write to message queue.

OpenMode

enum Arp::System::Commons::Ipc::MessageQueue::OpenMode

strong

Supported opening modes for message queues.

Enumerator
CreateNew	A new queue should be created. If one already exists an exception will be thrown.
Open	An already existing queue should be opened. An exception will be thrown if the message could does not exists yet.
OpenOrCreate	An already existing queue should be opened. If no one exists yet, a new one will be created.

Constructor & Destructor Documentation

MessageQueue() [1/3]

Arp::System::Commons::Ipc::MessageQueue::MessageQueue	(	const String &	name,
		bool	blocking = false
	)

Tries to open an already existing message queue.

Parameters

name	Name of message queue to be opened. Must be of the form /somename.
blocking	Flag indicating if queue should be opened in blocking mode.

Exceptions

Arp::System::Commons::InvalidOperationException	if message queues are not supported.
Arp::Exception	with additional error message if the queue could not be created by the operating system.

MessageQueue() [2/3]

Arp::System::Commons::Ipc::MessageQueue::MessageQueue	(	const String &	name,
		OpenMode	openMode,
		Access	permission = Access::ReadWrite,
		bool	blocking = false
	)

Tries to construct a new message queue based on assigned parameters.

Parameters

name	Name of message queue to be opened. Must be of the form /somename.
openMode	Opening mode for message queue.
permission	Determines access permissions for object owner.
blocking	Flag indicating if queue should be opened in blocking mode.

Exceptions

Arp::System::Commons::InvalidOperationException	if message queues are not supported.
Arp::Exception	with additional error message if the queue could not be created by the operating system.

MessageQueue() [3/3]

Arp::System::Commons::Ipc::MessageQueue::MessageQueue	(	const String &	name,
		OpenMode	openMode,
		Access	permission,
		bool	blocking,
		long	maxmsg,
		long	msgsize
	)

Tries to construct a new message queue based on assigned parameters.

Parameters

name	Name of message queue to be opened. Must be of the form /somename.
openMode	Opening mode for message queue.
permission	Determines access permissions for object owner.
blocking	Flag indicating if queue should be opened in blocking mode.
maxmsg	Amount of messages that can be stored by the message queue internally.
msgsize	Maximal amount of bytes of a single message.

Exceptions

Arp::System::Commons::InvalidOperationException	if message queues are not supported.
Arp::Exception	with additional error message if the queue could not be created by the operating system.

~MessageQueue()

Arp::System::Commons::Ipc::MessageQueue::~MessageQueue

(

void

)

Destructs this instance and closes the message queue.

The message queue is not deleted until Unlink is called. That is, a new object instance for the same message queue will reopen the previously created queue.

Member Function Documentation

Close()

void Arp::System::Commons::Ipc::MessageQueue::Close

(

)

Closes the message queue.

GetMaxMessageCount()

long Arp::System::Commons::Ipc::MessageQueue::GetMaxMessageCount

(

)

const

Queries the maximal amount of messages that can be stored inside the message queue.

Exceptions

Arp::Exception

with additional error information.

Returns

Maximal amount of messages that can be stored inside the message queue.

GetMaxMessageSize()

long Arp::System::Commons::Ipc::MessageQueue::GetMaxMessageSize

(

)

const

Queries the maximal supported byte-size of a message.

Exceptions

Arp::Exception

with additional error information.

Returns

Maximal supported byte-size of a message.

GetMessageCount()

long Arp::System::Commons::Ipc::MessageQueue::GetMessageCount

(

)

const

Queries the current amount of message stored in the message queue.

Exceptions

Arp::Exception

with additional error information.

Returns

Current amount of message stored in the message queue.

IsBlocking()

bool Arp::System::Commons::Ipc::MessageQueue::IsBlocking

(

)

const

Checks if this message queue was created in blocking mode.

Returns

True if message queue was created in blocking mode, otherwise false is returned.

Receive()

size_t Arp::System::Commons::Ipc::MessageQueue::Receive	(	char *	pBuffer,
		size_t	len,
		unsigned int &	prio,
		Milliseconds	timeoutMs = Milliseconds(0)
	)

Receives a message from the queue.

Parameters

pBuffer	Pointer to pre-allocate buffer where message can be stored.
len	Capacaity of buffer in bytes.
prio	Container variable storing the priority of the received message.
timeoutMs	Timeout for call in milliseconds. If set to zero the call blocks until a message can be read from the queue.

Exceptions

Arp::Exception

with additional error information.

Returns

Amount of bytes read from message queue. A timeout or an empty non-blocking queue is signaled by a return value of 0.

Send()

void Arp::System::Commons::Ipc::MessageQueue::Send	(	const char *	pMsg,
		size_t	len,
		unsigned int	prio,
		Milliseconds	timeoutMs = Milliseconds(0)
	)

Sends a message to the queue.

Parameters

pMsg	Pointer to message to be send to queue.
len	Byte-length of message.
prio	Priority of message.
timeoutMs	Timeout for send call in milliseconds. If set to zero the call blocks until the message can be send.

Exceptions

Arp::Exception

with additional error information.

Unlink()

void Arp::System::Commons::Ipc::MessageQueue::Unlink

(

)

Deletes the message queue.

The name of the message queue will be deleted immediately from the file system. The queue itself remains until every reference to the queue is closed.

Exceptions

Arp::Exception

with additional error information.

---

The documentation for this class was generated from the following file:

• Arp/System/Commons/Ipc/MessageQueue.hpp