POSIX::RT::MQ - Perl interface for POSIX Message Queues
use POSIX::RT::MQ; my $mqname = '/some_queue'; my $attr = { mq_maxmsg => 1024, mq_msgsize => 256 }; my $mq = POSIX::RT::MQ->open($mqname, O_RDWR|O_CREAT, 0600, $attr) or die "cannot open $mqname: $!\n"; $mq->send('some_message', 0) or die "cannot send: $!\n"; my ($msg, $prio) = $mq->receive or die "cannot receive: $!\n";
POSIX::RT::MQ provides an OO-style interface to the POSIX message queues (mq_open() and friends), which are part of the POSIX Realtime Extension.
POSIX::RT::MQ
mq_open()
This documentation is not a POSIX message queues tutorial. It describes mainly the syntax of Perl interface, please consult your operating system's manpages for general information on underlying calls. More references are listed in "SEE ALSO".
A wrapper for the mq_open() function.
$mq = open('/some_q1', O_RDWR); $mq = open('/some_q2', O_RDWR|O_CREAT, 0600); $attr = { mq_maxmsg=>1000, mq_msgsize=>2048 }; $mq = open('/some_q3', O_RDWR|O_CREAT, 0600, $attr);
Opens a message queue $name and returns a reference to a new object.
$name
Two optional arguments $mode and $attr are used when a new message queue is created. $mode specifies permissions bits set for the new queue and $attr (a hash reference) specifies the message queue attributes for the new queue.
$mode
$attr
The $attr represents the struct mq_attr. The following keys are recognized and their values are interpreted as the similary named structure fields:
struct mq_attr
mq_flags mq_maxmsg mq_msgsize mq_curmsgs
Usually only mq_maxmsg and mq_msgsize are respected by the underlying mq_open() function, the other fields (if present) are just ignored.
mq_maxmsg
mq_msgsize
On error returns undef.
undef
A wrapper for the mq_close() function.
mq_close()
Usually there is no need to call it manually. When the objects created by open() method is destroyed the underlying message queue gets closed automatically by destructor.
open()
A wrapper for the mq_getattr() and mq_setattr() functions.
mq_getattr()
mq_setattr()
$current_attr = $mq->attr(); $old_attr = $mq->attr($new_attr); # set the non-blocking mode: $attr = $mq->attr(); $attr->{mq_flags} |= O_NONBLOCK; $mq->attr($attr);
If called without arguments returns the message queue arrtibutes as a hash reference.
If called with an argument (a hash reference) sets message queue attributes as per $new_attr and returns the old attributes.
$new_attr
Usually only mq_flags is respected by the underlying mq_setattr() function, the other fields (if present) are just ignored.
mq_flags
However the hash reference returned by attr() will always contain all key/value pairs listed above.
attr()
See also the description of blocking() method.
blocking()
A wrapper for the mq_receive() function.
mq_receive()
$msg = $mq->receive(); ($msg, $prio) = $mq->receive();
Gets a message from the queue. In scalar context returns just the message, in list context returns a two-element array which contains the message as the first element and it's priority as the second.
On errror returns undef or an empty list.
A wrapper for the mq_timedeceive() function.
mq_timedeceive()
$msg = $mq->timedreceive($timeout); ($msg, $prio) = $mq->receive();
Gets a message from the queue waiting for at most $timeout seconds. In scalar context returns just the message, in list context returns a two-element array which contains the message as the first element and it's priority as the second.
On errror or timeout returns undef or an empty list.
A wrapper for the mq_send() function.
mq_send()
$msg = 'some message'; $mq->send($msg);
Sends the content of $msg to the queue as a message of priority $prio. If $prio is omitted it will be set to 0.
$msg
$prio
0
Returns true on success, undef on error.
A wrapper for the mq_unlink() function.
mq_unlink()
POSIX::RT::MQ->unlink($name); $mq->unlink();
When called as POSIX::RT::MQ->unlink($name) unlinks the message queue $name.
POSIX::RT::MQ->unlink($name)
When called as $mq->unlink() unlinks the queue which corresponds to the $mq object (the one that was supplied to open() at $mq creation). Note that the queue will be not closed, only unlinked. It will remain functional (but 'anonymous') until closed by all current users. Also, subsequent calls to $mq->name will return undef if $mq->unlink completes successfully.
$mq->unlink()
$mq->name
$mq->unlink
On errror returns undef.
A limited wrapper for the mq_notify() function.
mq_notify()
my $got_usr1 = 0; local $SIG{USR1} = sub { $got_usr1 = 1 }; $mq->notify(SIGUSR1) or warn "cannot notify(SIGUSR1): $!\n";
If called with an argument $signo this method registers the calling process to be notified of message arrival at an empty message queue in question. At any time, only one process may be registered for notification by a specific message queue.
$signo
If called without arguments and the process is currently registered for notification by the message queue in question, the existing registration is removed.
Return true on success, undef on error.
Currently this module dosn't support the full mq_notify() semantic and doesn't let the user to provide his own struct sigevent.
struct sigevent
The semantic of $mq->notify($signo) is equivalent in C to:
$mq->notify($signo)
struct sigevent sigev; sigev.sigev_notify = SIGEV_SIGNAL; sigev.sigev_signo = $signo sigev.sigev_value.sival_int = 0; mq_notify(mqdes, &sigev);
The semantic of $mq->notify() is equivalent in C to:
$mq->notify()
mq_notify(mqdes, NULL);
Please refer to documents listed in "SEE ALSO" for a complete description of notifications.
A convenience method.
$mq->blocking(0); # now in non-blocking mode ... $mq->blocking(1); # now in blocking mode
If called with an argument blocking() will turn on non-blocking behavior of the message queue in question if BOOL is false, and turn it off if BOOL is true.
BOOL
blocking() will return the value of the previous setting, or the current setting if BOOL is not given.
You may get the same results by using the attr() method.
$name = $mq->name();
Returns either the queue name as it was supplied to open() or undef if $mq->unlink was (successfully) called before.
$fd = $mq->mqdes();
Returns the message queue descriptor. On some operating systems (Linux, FreeBSD) the message queue descriptor is a regular file descripter that can be used with select / poll / etc.
Access to the MQ_OPEN_MAX constant.
$open_max = POSIX::RT::MQ::MQ_OPEN_MAX;
Access to the MQ_PRIO_MAX constant.
$prio_max = POSIX::RT::MQ::MQ_PRIO_MAX;
mq_notify() function is not fully supported.
mq_open, mq_close, mq_unlink, mq_getattr, mq_setattr, mq_send, mq_receive, mq_notify
The Single UNIX Specification, Version 2 (http://www.unix.org/version2/)
The Single UNIX Specification, Version 3 (http://www.unix.org/version3/)
The Base Definitions volume of IEEE Std 1003.1-2001.
Ilja Tabachnik <billy@arnis-bsl.com> (Original author)
Wieger Opmeer <wiegerop@cpan.org>
Thanks to Jim Dodgen for the timedreceive code
Copyright (C) 2003, Ilja Tabachnik
Copyright (C) 2019, 2020 Wieger Opmeer
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install POSIX::RT::MQ, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POSIX::RT::MQ
CPAN shell
perl -MCPAN -e shell install POSIX::RT::MQ
For more information on module installation, please visit the detailed CPAN module installation guide.