NAME

Messaging::Courier - asynchronous and synchronous access to a message queue.

SYNOPSIS

  use Messaging::Courier;

  my $c = Messaging::Courier->new();

  $m = $c->receive();
  $c->send($m);

  $m = $c->ask($m);

DESCRIPTION

Messaging::Courier is an interface into a message queue. It provides both synchronous and asynchronous access to the queue.

The message queue that Courier currently uses is Spread (http://www.spread.org/). This must be installed before using and testing this module. The module assumes that Spread is installed and that the spread daemon is running on the local machine.

INHERITANCE

Messaging::Courier inherits from the EO class.

CONSTRUCTOR

In addition to the constructor provided by its parent class Messaging::Courier provides the following constructors:

new( [Peer => SCALAR [, Port => SCALAR]] )

Provides a connection to the default queue. Peer defaults to 127.0.0.1 (localhost), and Port defaults to 4803 (the default spread port). By specifiying Peer or Port arguments the queue that Messaging::Courier connects to can be altered.

  my $c = Messaging::Courier->new();

All constructors can throw two exceptions additional to those thrown by the default constructor:

• Messaging::Courier::Error::CouldNotConnect

  Thrown when Messaging::Courier cannot connect to the message queue.

• Messaging::Courier::Error::CouldNotJoin

  Thrown when Messaging::Courier cannot join the correct group on the message queue.

METHODS

send( MESSAGE )

Sends a message to the queue. The message, provided as MESSAGE should be an object inheriting from Messaging::Courier::Message. Will throw an EO::Error::InvalidParameters exception in the case that MESSAGE is not a Messaging::Courier::Message.

  $c->receive(1);

receive( [TIMEOUT[, REPLYING]] )

Receives a message from the queue. If called without a TIMEOUT or a TIMEOUT set to zero any call to receive will block. If a timeout is specified receive does not block but returns undef in the case that it does not receive a message. If REPLYING is specified it should be a Messaging::Courier::Message object that you are waiting for a reply to. If this is the case receive will only ever return a message that is in reply to the message specified by REPLYING. The receive method will throw an EO::Error::InvalidParameters object in the case that the parameters sent do not match this specification.

  my $m = $c->receive(1);

ask( MESSAGE[, TIMEOUT] )

Send and receive a message MESSAGE. ask() returns a Messaging::Courier::Message object unless a TIMEOUT is specified and no message is received in that period. If this is the case undef is returned instead.

  my $r = $c->ask($m, 1);

ask_many( MESSAGE, TIMEOUT )

This sends a message MESSAGE. ask_many() returns all the messages that are a reply to MESSAGE

  my @received = $c->ask_many($m);

id()

returns the id of this Messaging::Courier connection. The id is appended to all Frames that are sent on the wire.

mailbox()

returns the mailbox of the connection to spread. This is a spread specific value and should not be relied apon.

name()

returns the name of the connection to Spread

private_group()

returns the private group that this connection to spread is a member of. This is a spread specific value and should not be relied apon.

reconnect()

disconnects and reconnects to Spread. This might be useful if your program sends a lot of messages but does not want to process any.

SEE ALSO

Messaging::Courier::Message, Messaging::Courier::Frame

AUTHORS

James A. Duncan <jduncan@fotango.com>, Leon Brocard <lbrocard@fotango.com>

COPYRIGHT

Copyright 2003-4 Fotango Ltd. All Rights Reserved.