Messaging::Courier - asynchronous and synchronous access to a message queue.
use Messaging::Courier; my $c = Messaging::Courier->new(); $m = $c->receive(); $c->send($m); $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 (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.
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 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:
Thrown when Messaging::Courier cannot connect to the message queue.
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);
- 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);
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.
James A. Duncan <email@example.com>, Leon Brocard <firstname.lastname@example.org>
Copyright 2003-4 Fotango Ltd. All Rights Reserved.