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


  use Messaging::Courier;

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

  $m = $c->receive();

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


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


Messaging::Courier inherits from the EO class.


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


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.

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

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

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


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


returns the name of the connection to Spread


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.


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


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


James A. Duncan <>, Leon Brocard <>


Copyright 2003-4 Fotango Ltd. All Rights Reserved.