This class represents an POSIX message queue descriptor (mqd_t) object. It matches the C API for POSIX messages queues closely.
See the README for examples on how to use it.
An analogous Struct to "struct mq_attr" in C. This may be used in arguments for POSIX_MQ.new and POSIX_MQ#attr=. POSIX_MQ#attr returns an instance of this class.
See the mq_getattr(3) manpage for more information on the values.
The maximum number of open message descriptors supported by the system. This may be -1, in which case it is dynamically set at runtime. Consult your operating system documentation for system-specific information about this.
The maximum priority that may be specified for POSIX_MQ#send On POSIX-compliant systems, this is at least 31, but some systems allow higher limits. The minimum priority is always zero.
POSIX_MQ.for_fd(socket) => mq source
Adopts a socket as a POSIX message queue. Argument will be checked to ensure it is a POSIX message queue socket.
This is useful for adopting systemd sockets passed via the ListenMessageQueue directive. Returns a POSIX_MQ instance. This method is only available under Linux and FreeBSD and is not intended to be portable.
POSIX_MQ.new(name [, flags [, mode [, mq_attr]]) => mq source
Opens a POSIX message queue given by name. name should start with a slash ("/") for portable applications.
If a Symbol is given in place of integer flags, then:
:r is equivalent to IO::RDONLY
:w is equivalent to IO::CREAT|IO::WRONLY
:rw is equivalent to IO::CREAT|IO::RDWR
mode is an integer and only used when IO::CREAT is used. mq_attr is a POSIX_MQ::Attr and only used if IO::CREAT is used. If mq_attr is not specified when creating a queue, then the system defaults will be used.
See the manpage for mq_open(3) for more details on this function.
open (*args) { |mq| ... } sourceOpens a POSIX message queue and performs operations on the given block, closing the message queue at exit. All all arguments are passed to POSIX_MQ.new.
POSIX_MQ.unlink(name) => 1 source
Unlinks the message queue given by name. The queue will be destroyed when the last process with the queue open closes its queue descriptors.
mq << string => mq source
Inserts the given string into the message queue with a default priority of 0 and no timeout.
Returns itself so its calls may be chained. This use is only recommended only for users who expect blocking behavior from the queue.
mq.attr => mq_attr source
Returns a POSIX_MQ::Attr struct containing the attributes of the message queue. See the mq_getattr(3) manpage for more details.
mq.attr = POSIX_MQ::Attr(IO::NONBLOCK) => mq_attr source
Only the IO::NONBLOCK flag may be set or unset (zero) in this manner. See the mq_setattr(3) manpage for more details.
Consider using the POSIX_MQ#nonblock= method as it is easier and more natural to use.
mq.autoclose = boolean => boolean source
Determines whether or not the mq will be closed automatically at finalization.
mq.autoclose? => boolean source
Returns whether or not the mq will be closed automatically at finalization.
clone ()
There's no point in ever cloning a POSIX_MQ object. All send/receive operations are atomic and only one native thread may be notified at a time
mq.close => nil source
Closes the underlying message queue descriptor. If this descriptor had a registered notification request, the request will be removed so another descriptor or process may register a notification request. Message queue descriptors are automatically closed by garbage collection.
mq.closed? => true or false source
Returns true if the message queue descriptor is closed and therefore unusable, otherwise false
dup () source
There's no point in ever duping a POSIX_MQ object. All send/receive operations are atomic and only one native thread may be notified at a time
mq.name => string source
Returns the string name of message queue associated with mq
mq.nonblock = boolean => boolean source
Enables or disables non-blocking operation for the message queue descriptor. Errno::EAGAIN will be raised in situations where the queue would block. This is not compatible with timeout arguments to POSIX_MQ#send and POSIX_MQ#receive.
mq.nonblock? => true or false source
Returns the current non-blocking state of the message queue descriptor.
notify (&block) source
Executes the given block upon reception of the next message in an empty queue. If the message queue is not empty, then this block will only be fired after the queue is emptied and repopulated with one message.
This block will only be executed upon the arrival of the first message and must be reset/reenabled for subsequent notifications. This block will execute in a separate Ruby Thread (and thus will safely have the GVL by default).
This method is only supported on platforms that implement SIGEV_THREAD functionality in mq_notify(3). So far we only know of glibc + Linux supporting this. Please let us know if your platform can support this functionality and are willing to test for us <ruby-posix-mq@yhbt.net>
As far as we can tell, this method is not very useful nor efficient. You would be better served using signals or just blocking. On Linux and FreeBSD, you can use POSIX_MQ with I/O multiplexing (IO.select, EventMachine), too.
mq.notify = signal => signal source
Registers the notification request to deliver a given signal to the current process when message is received. If signal is nil, it will unregister and disable the notification request to allow other processes to register a request. If signal is false, it will register a no-op notification request which will prevent other processes from registering a notification. If signal is an IO object, it will spawn a thread upon the arrival of the next message and write one "\0" byte to the file descriptor belonging to that IO object. Only one process may have a notification request for a queue at a time, Errno::EBUSY will be raised if there is already a notification request registration for the queue.
Notifications are only fired once and processes must reregister for subsequent notifications.
For readers of the mq_notify(3) manpage, passing false is equivalent to SIGEV_NONE, and passing nil is equivalent of passing a NULL notification pointer to mq_notify(3).
mq.receive([buffer, [timeout]]) => [ message, priority ] source
Takes the highest priority message off the queue and returns an array containing the message as a String and the Integer priority of the message.
If the optional buffer is present, then it must be a String which will receive the data.
If the optional timeout is present, then it may be a Float or Integer specifying the timeout in seconds. Errno::ETIMEDOUT will be raised if timeout has elapsed and there are no messages in the queue.
On some older systems, the timeout argument is not currently supported and may raise NotImplementedError if timeout is used.
mq.send(string [,priority[, timeout]]) => true source
Inserts the given string into the message queue with an optional, unsigned integer priority. If the optional timeout is specified, then Errno::ETIMEDOUT will be raised if the operation cannot complete before timeout seconds has elapsed. Without timeout, this method may block until the queue is writable.
On some older systems, the timeout argument is not currently supported and may raise NotImplementedError if timeout is used.
mq.shift([buffer, [timeout]]) => message source
Takes the highest priority message off the queue and returns the message as a String.
If the optional buffer is present, then it must be a String which will receive the data.
If the optional timeout is present, then it may be a Float or Integer specifying the timeout in seconds. Errno::ETIMEDOUT will be raised if timeout has elapsed and there are no messages in the queue.
On some older systems, the timeout argument is not currently supported and may raise NotImplementedError if timeout is used.
mq.to_io => IO source
Returns an IO.select-able IO object. This method is only available under Linux and FreeBSD and is not intended to be portable.
mq.tryreceive([buffer [, timeout]]) => [ message, priority ] or nil source
Exactly like POSIX_MQ#receive, except it returns nil instead of raising Errno::EAGAIN when non-blocking operation is desired.
This does not guarantee non-blocking behavior, the message queue must be made non-blocking before calling this method.
mq.trysend(string [,priority[, timeout]]) => +true+ or +false+ source
Exactly like POSIX_MQ#send, except it returns false instead of raising Errno::EAGAIN when non-blocking operation is desired and returns true on success instead of nil.
This does not guarantee non-blocking behavior, the message queue must be made non-blocking before calling this method.
mq.tryshift([buffer [, timeout]]) => message or nil source
Exactly like POSIX_MQ#shift, except it returns nil instead of raising Errno::EAGAIN when non-blocking operation is desired.
This does not guarantee non-blocking behavior, the message queue must be made non-blocking before calling this method.
mq.unlink => mq source
Unlinks the message queue to prevent other processes from accessing it. All existing queue descriptors to this queue including those opened by other processes are unaffected. The queue will only be destroyed when the last process with open descriptors to this queue closes the descriptors.
mail archives: https://yhbt.net/ruby-posix-mq/ http://ou63pmih66umazou.onion/ruby-posix-mq/ nntp://news.public-inbox.org/inbox.comp.lang.ruby.posix-mq nntp://ou63pmih66umazou.onion/inbox.comp.lang.ruby.posix-mq public: ruby-posix-mq@yhbt.net source code: git clone https://yhbt.net/ruby_posix_mq.git torsocks git clone http://ou63pmih66umazou.onion/ruby_posix_mq.git