SharedMemoryQueue< T > Class Template Reference

A blocking, shared memory queue that uses the Boost interprocess library. More...

#include <SharedMemoryQueue.hpp>

Inheritance diagram for SharedMemoryQueue< T >:

Collaboration diagram for SharedMemoryQueue< T >:

Public Member Functions
	SharedMemoryQueue (unsigned int capacity, bool throwOnOversize_=false)
	Create a shared memory queue of type T and with the specified capacity. More...
	SharedMemoryQueue (unsigned int capacity, unsigned int bufferSize_, bool throwOnOversize_=false)
	Create a shared memory queue of type T, with the specified capacity, and with the specified buffer size. More...
	SharedMemoryQueue (unsigned int capacity, std::string name_, bool throwOnOversize_=false)
	Create a shared memory queue of type T and with the specified capacity,. More...
	SharedMemoryQueue (unsigned int capacity, unsigned int bufferSize_, std::string name_, bool throwOnOversize_=false)
	Create a shared memory queue of type T, with the specified capacity and buffer size. More...
	SharedMemoryQueue (OpenOrCreateSelector, unsigned int capacity, std::string name_, bool throwOnOversize_=false)
	Open or create a shared memory queue of type T and with the specified capacity. More...
	SharedMemoryQueue (OpenOrCreateSelector, unsigned int capacity, unsigned int bufferSize_, std::string name_, bool throwOnOversize_=false)
	Open or create a shared memory queue of type T, with the specified capacity and buffer size. More...
	SharedMemoryQueue (std::string name_, bool throwOnOversize_=false)
	Open an existing shared memory queue with the specified name. More...
T	dequeue () override
	Dequeue an object. More...
bool	empty () const override
	Returns true if the queue is empty. More...
void	enqueue (T &&object) override
	Enqueue an object with a priority of zero. More...
void	enqueue (const T &object, unsigned int priority)
	Enqueue an object with the specified priority. More...
bool	full () const override
	Returns true if the queue is full. More...
std::string	getName () const
	Get the name of the queue. More...
T	tryDequeue () override
	Try to dequeue an object. More...
T	tryDequeue (std::chrono::milliseconds waitTime) override
	Try to dequeue an object, waiting the specified time before giving up. More...

Detailed Description

template<typename T>
class Balau::Interprocess::SharedMemoryQueue< T >

A blocking, shared memory queue that uses the Boost interprocess library.

This class encapsulates calls to the Boost interprocess library in order to create a shared memory queue, and implements the Balau::Container::BlockingQueue API.

The implementation uses the Boost serialization library for marshalling and unmarshalling of objects. In order to use the queue, the object type T must provide Boost serialize or save/load methods.

This queue implementation has the following concurrency guarantees.

The queue can be used for concurrent enqueues and concurrent dequeues across processes/threads if the maximum enqueued serialised object size + header size is guaranteed to be smaller than the shared memory queue buffer size.

If the above guarantee cannot be met, the queue can be used for concurrent enqueues across processes/threads, but only synchronised dequeues in a single process. This is due to the dequeueing of partial objects occurring in one process, rendering the continuation of the dequeueing of that object impossible in other processes.

If this limitation is breached, the application(s) will be defective due to:

• dequeues of partial objects occurring across different processes/threads;
• unprotected mutation of the std::dequeue used to hold pending dequeue buffers.

Note that the second of the above points necessitates a single threaded or mutex protected dequeueing in the dequeueing process when oversize objects are being enqueued.

Template Parameters

T	the type of enqueued/dequeued objects

Constructor & Destructor Documentation

SharedMemoryQueue() [1/7]

SharedMemoryQueue ( unsigned int  capacity, bool  throwOnOversize_ = false  )

inlineexplicit

Create a shared memory queue of type T and with the specified capacity.

The name is automatically generated.

SharedMemoryQueue() [2/7]

SharedMemoryQueue ( unsigned int  capacity, unsigned int  bufferSize_, bool  throwOnOversize_ = false  )

inline

Create a shared memory queue of type T, with the specified capacity, and with the specified buffer size.

The name is automatically generated.

SharedMemoryQueue() [3/7]

SharedMemoryQueue ( unsigned int  capacity, std::string  name_, bool  throwOnOversize_ = false  )

inline

Create a shared memory queue of type T and with the specified capacity,.

The specified name is used.

SharedMemoryQueue() [4/7]

SharedMemoryQueue ( unsigned int  capacity, unsigned int  bufferSize_, std::string  name_, bool  throwOnOversize_ = false  )

inline

Create a shared memory queue of type T, with the specified capacity and buffer size.

The specified name is used.

Exceptions

SizeException

if the buffer size is below the minimum required buffer size

SharedMemoryQueue() [5/7]

SharedMemoryQueue ( OpenOrCreateSelector  , unsigned int  capacity, std::string  name_, bool  throwOnOversize_ = false  )

inline

Open or create a shared memory queue of type T and with the specified capacity.

The specified name is used.

In an existing queue exists, the capacity is ignored.

SharedMemoryQueue() [6/7]

SharedMemoryQueue ( OpenOrCreateSelector  , unsigned int  capacity, unsigned int  bufferSize_, std::string  name_, bool  throwOnOversize_ = false  )

inline

Open or create a shared memory queue of type T, with the specified capacity and buffer size.

The specified name is used.

In an existing queue exists, the capacity and buffer size are ignored.

Exceptions

SizeException

if the buffer size is below the minimum required buffer size

SharedMemoryQueue() [7/7]

SharedMemoryQueue ( std::string  name_, bool  throwOnOversize_ = false  )

inlineexplicit

Open an existing shared memory queue with the specified name.

Member Function Documentation

dequeue()

T dequeue ( )

inlineoverridevirtual

Dequeue an object.

When the queue is being used with oversize objects (which require multiple queue receives, this method may only be used via synchronised calls.

Implements BlockingQueue< T >.

empty()

bool empty ( ) const

inlineoverridevirtual

Returns true if the queue is empty.

Given the concurrent nature of block queues, this operation is approximate.

Implements BlockingQueue< T >.

enqueue() [1/2]

void enqueue ( T &&  object )

inlineoverridevirtual

Enqueue an object with a priority of zero.

If the queue is full, this call will block until there is a slot available.

Implements BlockingQueue< T >.

enqueue() [2/2]

void enqueue ( const T &  object, unsigned int  priority  )

inline

Enqueue an object with the specified priority.

If the queue is full, this call will block until there is a slot available.

Exceptions

SizeException

if enqueueing of oversize objects was set to forbidden and the object is oversize

full()

bool full ( ) const

inlineoverridevirtual

Returns true if the queue is full.

Given the concurrent nature of block queues, this operation is approximate.

Implements BlockingQueue< T >.

getName()

std::string getName ( ) const

inline

Get the name of the queue.

This can be passed to other processes in order to open the queue.

tryDequeue() [1/2]

T tryDequeue ( )

inlineoverridevirtual

Try to dequeue an object.

When the queue is being used with oversize objects (which require multiple queue receives, this method may only be used via synchronised calls.

Implements BlockingQueue< T >.

tryDequeue() [2/2]

T tryDequeue ( std::chrono::milliseconds  waitTime )

inlineoverridevirtual

Try to dequeue an object, waiting the specified time before giving up.

When the queue is being used with oversize objects (which require multiple queue receives, this method may only be used via synchronised calls.

Implements BlockingQueue< T >.

---

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

• SharedMemoryQueue.hpp (3)