Welcome to ipcqueue’s documentation!

This package provides SYS V and POSIX message queues to exchange data among processes. Both queues have similar functionality with some differences. Queues are persistent in the kernel unless either queue is closed/unlinked or system is shut down. Unlike multiprocessing.Queue, the same queue can be joined by different processes according to its unique name/key, it’s not necessary to fork main process. Be careful if you use signals in your application, because signal interrupts sending or receiving message.

SYS V queue provides receiving messages according to their message type, but doesn’t provide blocking with timeout. See http://man7.org/linux/man-pages/man7/svipc.7.html.

POSIX queue provides receiving messages according their priority, blocking with timeout is supported, but doesn’t provide message’s type. See http://man7.org/linux/man-pages/man7/mq_overview.7.html.

POSIX message queue

Interprocess POSIX message queue implementation.

exception ipcqueue.posixmq.QueueError(errno, msg=None)

Indicates Queue error. Contains additional attributes errno and msg. Value of the errno is system dependent, do don’t use numeric codes directly, use constants QueueError.ERROR, QueueError.INVALID_VALUE, QueueError.NO_PERMISSIONS, QueueError.NO_SYSTEM_RESOURCES, QueueError.INVALID_DESCRIPTOR, QueueError.INTERRUPTED, QueueError.TOO_BIG_MESSAGE, QueueError.TIMEOUT and QueueError.DOES_NOT_EXIST.

Remove a message queue name.

class ipcqueue.posixmq.Queue(name, maxsize=10, maxmsgsize=1024)

POSIX message queue.

Constructor for message queue. name is an unique identifier of the queue, must starts with /. maxsize is an integer that sets the upperbound limit on the number of items that can be placed in the queue (maximum value depends on system limit). maxmsgsize is a maximum size of the message in bytes (maximum value depends on hard system limit).

close()

Close a message queue.

get(block=True, timeout=None)

Remove and return an item from the queue. If block is True and timeout is None (the default), block if necessary until an item is available. If timeout is a positive number, it blocks at most timeout seconds and raises the queue.Empty exception if no item was available within that time. Otherwise (block is False), return an item if one is immediately available, else raise the queue.Empty exception (timeout is ignored in that case).

get_nowait()

Get and return an item from queue, equivalent to get(block=False).

put(item, block=True, timeout=None, priority=0, pickle_protocol=1)

Put item into the queue. If block is True and timeout is None (the default), block if necessary until a free slot is available. If timeout is a positive number, it blocks at most timeout seconds and raises the queue.Full exception if no free slot was available within that time. Otherwise (block is False), put an item on the queue if a free slot is immediately available, else raise the queue.Full exception (timeout is ignored in that case). priority is a priority of the message, the highest valued items are retrieved first. Items is serialized by Python’s pickle module, pickle_protocol is a protocol’s version.

put_nowait(item, priority=0, pickle_protocol=1)

Put item into the queue, equivalent to put(item, block=False). priority is a priority of the message, the highest valued items are retrieved first. Items is serialized by Python’s pickle module, pickle_protocol is a protocol’s version.

qattr()

Return attributes of the message queue as a dict: {'size': 5, 'max_size': 10, 'max_msgbytes': 1024}.

qsize()

Return the approximate size of the queue. Note, qsize() > 0 doesn’t guarantee that a subsequent get() will not block, nor will qsize() < maxsize guarantee that put() will not block.

Remove a message queue. POSIX message queues have kernel persistence, so if it’s not removed by this method, a message queue will exist until the system is shut down.

>>> from ipcqueue import posixmq
>>> q = posixmq.Queue('/foo')
>>> q.qsize()
0
>>> q.put([1, 'A'])
>>> q.put([2, 'B'], priority=2)
>>> q.put([3, 'C'], priority=0)
>>> q.qsize()
3
>>> q.get()
[2, 'B']
>>> q.get()
[1, 'A']
>>> q.get()
[3, 'C']
>>> q.close()
>>> q.unlink()

SYS V message queue

Interprocess SYS V message queue implementation.

exception ipcqueue.sysvmq.QueueError(errno, msg=None)

Indicates Queue error. Contains additional attributes errno and msg. Value of the errno is system dependent, do don’t use numeric codes directly, use constants QueueError.ERROR, QueueError.INVALID_VALUE, QueueError.NO_PERMISSIONS, QueueError.NO_SYSTEM_RESOURCES, QueueError.INVALID_DESCRIPTOR, QueueError.INTERRUPTED and QueueError.TOO_BIG_MESSAGE.

class ipcqueue.sysvmq.Queue(key=None, max_bytes=None)

SYS V message queue.

Constructor for message queue. key is an unique identifier of the queue, must be positive number or 0 for private queue. max_bytes is a maximum number of bytes allowed in queue (maximum value depends on hard system limit).

close()

Close a message queue.

get(block=True, msg_type=0)

Remove and return an item from the queue. If block argument is True, block if necessary until an item is available. Otherwise, return an item if one is immediately available, else raise the queue.Empty exception. msg_type specifies the type of requested message. If it’s 0, then the first message in the queue is read, if it’s greater than 0, then the first message in the queue of requested type is read and if it’s less than 0, then the first message in the queue with the lowest type less than or equal to the absolute value of msg_type will be read.

get_nowait(msg_type=0)

Get and return an item from queue, equivalent to get(block=False). msg_type specifies the type of requested message. If it’s 0, then the first message in the queue is read, if it’s greater than 0, then the first message in the queue of requested type is read and if it’s less than 0, then the first message in the queue with the lowest type less than or equal to the absolute value of msg_type will be read.

put(item, block=True, msg_type=1, pickle_protocol=1)

Put item into the queue. If block is True, block if necessary until a free slot is available. Otherwise, put an item on the queue if a free slot is immediately available, else raise the queue.Full exception. msg_type must be positive integer value, this value can be used by the receiving process for message selection. pickle_protocol is a format used by Python’s pickle.

put_nowait(item, msg_type=1, pickle_protocol=1)

Put item into the queue, equivalent to put(item, block=False). msg_type must be positive integer value, this value can be used by the receiving process for message selection. pickle_protocol is a format used by Python’s pickle.

qattr()

Return attributes of the message queue as a dict: {'size': 3, 'max_bytes': 8192}.

qsize()

Return the approximate size of the queue. Note, qsize() > 0 doesn’t guarantee that a subsequent get() will not block.

>>> from ipcqueue import sysvmq
>>> q = sysvmq.Queue(1)
>>> q.qsize()
>>> q.put([1, 'A'])
>>> q.put([2, 'B'], msg_type=2)
>>> q.put([3, 'C'], msg_type=2)
>>> q.put([4, 'D'], msg_type=1)
>>> q.qsize()
4
>>> q.get(msg_type=2)
[2, 'B']
>>> q.get()
[1, 'A']
>>> q.get()
[3, 'C']
>>> q.get()
[4, 'D']
>>> q.close()