NAME

Linux::Perl::mq - POSIX message queue

SYNOPSIS

my $mq = Linux::Perl::mq->new(
    name => 'my_message_queue',
    flags => ['CREAT'],

    # Only needed for message creation:
    msgsize => 16,
    maxmsg => 5,
    mode => 0644,
);

$mq->send( msg => 'Hello, world!' );

my $got_msg = $mq->receive( msgsize => 16 );

$mq->blocking(0);   # sets non-blocking mode
$mq->blocking();    # returns 0

my $attrs_hr = $mq->getattr();

# For select, epoll, or poll:
my $fileno = $mq->fileno();

METHODS

CLASS->unlink( $NAME )

Returns truthy if a queue is removed or falsy if no queue with the given $NAME exists.

Throws an exception on failure.

CLASS->new( %OPTS )

Creates a new read/write message queue object.

%OPTS are:

name
flags - Any/all/none of: CLOEXEC, NONBLOCK, CREAT, EXCL.
mode - Only relevant if the CREAT flag is given.
maxmsg - Only relevant if the CREAT flag is given.
msgsize - Only relevant if the CREAT flag is given.

CLASS->new_wronly( %OPTS )

Like new(), but the queue handle is write-only.

CLASS->new_rdonly( %OPTS )

Like new(), but the queue handle is read-only.

OBJ->fileno()

Returns the file descriptor number. This is useful, e.g., for use with select, epoll, or poll.

OBJ->getattr()

Returns a hashref of attributes that corresponds to struct mq_attr. See man 3 mq_getattr for details.

OBJ->blocking()

Imitates IO::Handle’s method of the same name. Returns a boolean that indicates whether the message queue handle is blocking.

OBJ->blocking( $BLOCKING_YN )

Sets the message queue handle as blocking or non-blocking.

OBJ->send( %OPTS )

Sends a message to the queue. An exception is thrown on failure, e.g., if the queue cannot accommodate another message.

msg - The message to send.
prio - Optional, the message priority. Defaults to 0 (highest priority).
timeout - Optional, in seconds. (Can be fractional.)

OBJ->receive( \$BUFFER, %OPTS )

Attempts to slurp a message from the queue.

$BUFFER is a pre-initialized buffer where the message will be stored. It must be at least as long as the message queue’s msgsize.