NAME

Spread::Messaging - A Perl extension to the Spread Group Communications toolkit

SYNOPSIS

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.

DESCRIPTION

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.

METHODS

new

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.

-port

This allows you to indicate which port number to use.

-host

This allows you to choose which host the Spread server is located on.

-timeout

This allows you to select a timeout.

-service_type

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.

-private_name

This allows you to choose a specifc private name for your private mailbox. This name can be used for unicast messages.

Example

$spread = Spread::Messaging->new(
    -port => "8000",
    -timeout => "10",
    -host => "spread.example.com",
    -private_name => "mymailbox"
);

callbacks

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.

-private

Use this callback if you want to handle private message exchanges. Private messages are delivered to the mailbox defined by $spread->private_group.

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

-join

Use this callback if you want to handle join messages from your groups. A message is sent whenever another entity joins a group.

-leave

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.

-disconnect

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.

-network

Use this callback if you want to handle network messages from your groups. This usually indicates a error within the Spread network.

-transition

Use this callback if you want to handle transistion messages from your groups. This usually indicates a state transititon within the Spread network.

Example

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

process

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.

ACCESSORS

entity

This method returns the entity that sent the message.

groups_joined

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.

group_members

This accessor returns the members of a group. This is an array.

Example

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

    }

}

EXPORTS

This module exports the following constants from Spread.pm.

UNRELIABLE_MESS
RELIABLE_MESS
FIFO_MESS
CAUSAL_MESS
AGREED_MESS
SAFE_MESS

SEE ALSO

Spread::Messaging::Transport
Spread::Messaging::Content

There are several other modules located on CPAN that already handle the Spread Group Communications toolkit. They are:

Spread.pm

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.

Spread::Message

Another wrapper module for Spread.pm. Please see this modules documentation for usage.

Spread::Session

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.

Messaging::Courier

Another wrapper module for Spread.pm. Please see this modules documentation for usage.

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.

AUTHOR

Kevin L. Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

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.