Spread::Messaging - A Perl extension to the Spread Group Communications toolkit
This module attempts to provide a simple and easy to use interface to the Spread Group Communications toolkit. It is a thin, object oriented layer over the toolkits Spread.pm. To use this module you also need Spread::Transport and Spread::Content, which this module inherits from.
To receive messages from a Spread network, your application could be as simple as this:
use Spread::Messaging; sub handle_group { my $spread = shift; printf("Message: %s\n", $spread->message); } main: { my $spread; $spread = Spread::Messaging->new(); $spread->join_group("test1"); $spread->callbacks(-group => \&handle_group); for (;;} { if ($spread->poll()) { $spread->process(); } sleep(1); } }
Or you could use an event module and do the following:
use Event; use Spread::Messaging; sub handle_group { my $spread = shift; printf("Message: %s\n", $spread->message); } main: { my $spread; $spread = Spread::Messaging->new(); $spread->join_group("test1"); $spread->callbacks(-group => \&handle_group); Event->io(fd => $spread->fd, cb => sub { $spread->process(); }); Event::loop(); }
But of course, this is never the case. This module will allow you to build your application as you see fit. All errors are signaled thru die(). The errors are returned thru object accessors. No structure is enforced upon the messages being sent. This module is designed for maximum flexibility.
This method inializes the object. Reasonable defaults are provided during this initializaion. By default, your program will connect to a Spread server on port 4803, on host "localhost", with a timeout of 5 seconds, along with a self generated private name, using a message type of "SAFE_MESS". To override these defaults you can use the following named parameters.
This allows you to indicate which port number to use.
This allows you to choose which host the Spread server is located on.
This allows you to select a timeout.
This allows you to choose a differant service type. The following types are valid:
UNRELIABLE_MESS RELIABLE_MESS FIFO_MESS CAUSAL_MESS AGREED_MESS SAFE_MESS
Please see the Spread documentation for the meaning of these service types.
This allows you to choose a specifc private name for your private mailbox. This name can be used for unicast messages.
$spread = Spread::Messaging->new( -port => "8000", -timeout => "10", -host => "spread.example.com", -private_name => "mymailbox" );
This method defines how message types are handled. Each callback will handle one type of message. If no callback is defined for a message type, the message will be discarded. There is no "default" message handler. The following named parameters have meaning.
Use this callback if you want to handle private message exchanges. Private messages are delivered to the mailbox defined by $spread->private_group.
Use this callback if you want to handle any group messages. What groups you receive messages from, is defined by your usage of $spread->join_group().
Use this callback if you want to handle join messages from your groups. A message is sent whenever another entity joins a group.
Use this callback if you want to handle leave messages from your groups. A message is sent whenever another entity leaves a group. The differance between leaving and disconnecting is that "leave" is voluntary.
Use this callback if you want to handle disconnect messages from your groups. A message is sent whenever another entity disconnects from a group. The differance between leaving and disconnecting is that "disconnect" is involuntary.
Use this callback if you want to handle network messages from your groups. This usually indicates a error within the Spread network.
Use this callback if you want to handle transistion messages from your groups. This usually indicates a state transititon within the Spread network.
sub handle_private { my ($spread) = @_; printf("Private message recieved\n"); } sub handle_group { my ($spread) = @_; if ($spread->group eq 'mygroup') { printf("Group message received from \"mygroup\"\n"); } } $spread->callbacks(-private => \&handle_private, -group => \&handle_group);
This method performs the actual message retrieval and dispatch depending on message type. If no callbacks are defined, nothing is done and the message is discarded.
This method returns the entity that sent the message.
This accessor returns the current groups that your application has joined. The returned value is an array or undef if no groups have been joined yet.
This accessor returns the members of a group. This is an array.
@groups = $spread->groups_joined; foreach my $group (@groups) { @members = $spread->group_members($group); foreach my $member (@members) { printf("%s is a member of %s\n", $member, $group); } }
This module exports the following constants from Spread.pm.
Spread::Messaging::Transport Spread::Messaging::Content
There are several other modules located on CPAN that already handle the Spread Group Communications toolkit. They are:
This module is provided by the Spread toolkit to enable basic connectivity to a Spread server. It works, the interface is smiliar to the C API and you need to do all of the heavy hitting on your own.
Another wrapper module for Spread.pm. Please see this modules documentation for usage.
Another wrapper modules for Spread.pm. This module is the base for these modules:
Spread::Queue Spread::Queue::Fifo Spread::Queue::Sender Spread::Queue::Worker Spread::Queue::Manager Spread::Queue::ManagedWorker
Please read the documentation for these modules to see how they interact.
You also need to read the Spread documentation located at www.spread.org. This is the definative description on what the Spread system is all about. And should be considered mandatory reading for anybody attempting to use the toolkit.
Kevin L. Esteb, <kevin@kesteb.us>
Copyright (C) 2007 by Kevin L. Esteb
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.
To install Spread::Messaging, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Spread::Messaging
CPAN shell
perl -MCPAN -e shell install Spread::Messaging
For more information on module installation, please visit the detailed CPAN module installation guide.