mood.mqueue

Python POSIX message queues interface (Linux only)

POSIX message queues allow processes to exchange data in the form of messages.

See also: mq_overview - overview of POSIX message queues

---

MessageQueue(name, flags[, mode=0o600, maxmsg=-1, msgsize=-1])

• name (str)

  Each message queue is identified by a name of the form /somename; that is, a string consisting of an initial slash, followed by one or more characters, none of which are slashes. Two processes can operate on the same queue by passing the same name.

• flags (int)

  Exactly one of the following must be specified in flags:

  • O_RDONLY

    Open the queue to receive messages only.

  • O_WRONLY

    Open the queue to send messages only.

  • O_RDWR

    Open the queue to both send and receive messages.

  Zero or more of the following flags can additionally be ORed in flags:

  • O_CLOEXEC

    Enable the close-on-exec flag for the new file descriptor.

    See: Inheritance of File Descriptors and Secure File Descriptor Handling.

  • O_NONBLOCK

    Open the queue in nonblocking mode. In circumstances where receive() and send() would normally block, these methods instead raise BlockingIOError.

  • O_CREAT

    Create the message queue if it does not exist.

  • O_EXCL

    If O_CREAT was specified in flags, and a queue with the given name already exists, then raise FileExistsError.

  If O_CREAT is specified in flags, then three additional optional arguments can be supplied:

  • mode (int: 0o600)

    The mode argument specifies the permissions to be placed on the new queue. The permissions settings are masked against the process umask. mode may take one of the following values or bitwise ORed combinations of them:

    • S_IRWXU
    • S_IRUSR
    • S_IWUSR
    • S_IXUSR
    • S_IRWXG
    • S_IRGRP
    • S_IWGRP
    • S_IXGRP
    • S_IRWXO
    • S_IROTH
    • S_IWOTH
    • S_IXOTH

  • maxmsg (int: -1)

    maxmsg is an upper limit on the number of messages that may be placed on the queue using send(). If omitted or specified as a negative number, the value in /proc/sys/fs/mqueue/msg_default is used. The maximum value for maxmsg is defined in /proc/sys/fs/mqueue/msg_max.

  • msgsize (int: -1)

    msgsize is an upper limit on the size of messages that may be placed on the queue. If omitted or specified as a negative number, the value in /proc/sys/fs/mqueue/msgsize_default is used. The maximum value for msgsize is defined in /proc/sys/fs/mqueue/msgsize_max.

len(mq)

Return the number of messages in the message queue mq.

close()

Closes the message queue.

fileno() -> int

Returns the underlying file descriptor of the message queue.

send(message[, priority]) -> int

Sends one bytes-like message. Returns the number of bytes sent.

• priority (int: 0)

  Each message has an associated priority, and messages are always delivered to the receiving process highest priority first (messages are placed on the queue in decreasing order of priority, with newer messages of the same priority being placed after older messages with the same priority). Valid message priorities range from 0 (low) to os.sysconf("SC_MQ_PRIO_MAX") - 1 (high).

sendall(message[, priority])

Sends one bytes-like message. This calls send() repeatedly until all data is sent.

receive() -> bytes

Receives and returns one message.

notify([callback])

Register or unregister for delivery of an asynchronous notification when a new message arrives on an empty message queue.

Only one process can be registered to receive notification from a message queue.

Message notification occurs only when a new message arrives and the queue was previously empty. If the queue was not empty at the time notify() was called, then a notification will occur only after the queue is emptied and a new message arrives.

If another process or thread is waiting to read a message from an empty queue using receive(), then any message notification registration is ignored: the message is delivered to the process or thread calling receive(), and the message notification registration remains in effect.

Notification occurs once: after a notification is delivered, the notification registration is removed, and another process can register for message notification. If the notified process wishes to receive the next notification, it can use notify() to request a further notification. This should be done before emptying all unread messages from the queue (placing the queue in nonblocking mode is useful for emptying the queue of messages without blocking once it is empty).

When called with no argument, and the calling process is currently registered to receive notifications for this message queue, then the registration is removed; another process can then register to receive a message notification for this queue.

Otherwise callback can be:

• None: the calling process is registered as the target for notification, but when a message arrives, no notification is sent.
• a signal number: notify the process by sending the signal specified.
• a callable: upon message delivery, invoke callback (in a new thread) with the message queue as sole argument.

name (read only)

This queue's name.

flags (read only)

flags argument passed to the constructor.

mode (read only)

File mode. The constants and functions in the stat module (S_IMODE() or S_IFMT(), for example) can be used to interpret it.

maxmsg (read only)

Maximum number of messages.

msgsize (read only)

Maximum message size (in bytes).

closed (read only)

True if the message queue is closed (i.e. close() has been called). False otherwise.

blocking

Get/set the blocking mode of the queue. Set to False if you want to put the queue in nonblocking mode. The initial blocking mode is set by the presence/absence of O_NONBLOCK in the flags argument passed to the constructor.