NAME

POSIX::RT::MQ - Perl interface for POSIX Message Queues

SYNOPSIS

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";

DESCRIPTION

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.

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".

CONSTRUCTOR

open( $name, $oflag [, $mode [, $attr]] )

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.

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.

The $attr represents the struct mq_attr. The following keys are recognized and their values are interpreted as the similary named structure fields:

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.

On error returns undef.

DESTRUCTOR

DESTROY

A wrapper for the mq_close() function.

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.

METHODS

attr( [$new_attr] )

A wrapper for the mq_getattr() and mq_setattr() functions.

$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.

The $attr represents the struct mq_attr. The following keys are recognized and their values are interpreted as the similary named structure fields:

mq_flags
mq_maxmsg
mq_msgsize
mq_curmsgs

Usually only mq_flags is respected by the underlying mq_setattr() function, the other fields (if present) are just ignored.

However the hash reference returned by attr() will always contain all key/value pairs listed above.

On error returns undef.

receive

A wrapper for the mq_receive() function.

$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.

send( $msg [, $prio ] )

A wrapper for the mq_send() function.

$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.

Returns true on success, undef on error.

unlink( [$name] )

A wrapper for the mq_unlink() function.

POSIX::RT::MQ->unlink($name);
$mq->unlink();

When called as POSIX::RT::MQ->unlink($name) unlinks the message queue $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.

name

$name = $mq->name();

Returns either the queue name as it was supplied to open() or undef if $mq->unlink was (successfully) called before.

BUGS

mq_notify() function is not yet supported.

AUTHOR

Ilja Tabachnik <billy@arnis-bsl.com>

SEE ALSO

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.