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.

See also the description of blocking() method.

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.

On errror returns undef.

notify([ $signo ])

A limited wrapper for the mq_notify() function.

    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.

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.

The semantic of $mq->notify($signo) is equivalent in C to:

        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(mqdes, NULL);

Please refer to documents listed in "SEE ALSO" for a complete description of notifications.

blocking([ BOOL ])

A covinience 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.

blocking() will return the value of the previous setting, or the current setting if BOOL is not given.

On errror returns undef.

You may get the same results by using the attr() method.

name

A covinience method.

 $name = $mq->name();

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

CONSTANTS

MQ_OPEN_MAX

Access to the MQ_OPEN_MAX constant.

 $open_max = POSIX::RT::MQ::MQ_OPEN_MAX;     

MQ_PRIO_MAX

Access to the MQ_PRIO_MAX constant.

 $prio_max = POSIX::RT::MQ::MQ_PRIO_MAX;     

BUGS

mq_notify() function is not fully 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.