NAME

Spread::Message - provide messaging using the Spread toolkit

This product uses software developed by Spread Concepts LLC for use in the Spread toolkit. For more information about Spread see http://www.spread.org

SYNOPSIS

use Spread::Message;

my $mbox = Message->new(
    spread_name => '4803@host',
    name  => "down$$",
    group => ['devices-down'],
    #debug => 1,
    member_sub  => \&process_control,
    message_sub => \&process_data,
    timeout_sub => \&heartbeat,
);

sub process_control
{
    my $mbox = shift;
    my $loop = shift;
    # Process membership messages here. See examples
}

sub process_data
{
    my $mbox = shift;
    my $loop = shift;
    # Process the data here. See examples
}

sub heartbeat
{
    my $mbox = shift;
    my $loop = shift;
    # Process any timeouts here. See examples
}

while(1)
{
    # Process different data as required
    $mbox->rx(10,$loop);
    $loop++;

    # Extra processing of side effects created by the callbacks
}
$mbox->disconnect();

Other possibilites are:

# Connection
$mbox->connect;
$mbox->disconnect;

# Config
$mbox->configure(%config);
$spread_daemon = $mbox->spread_name;
$mbox->spread_name('3480@1.1.1.1');
$seed_name = $mbox->name;
$mbox->name('test');
$rv = $mbox->debug(); 
$mbox->debug(1);

# tx/rx messages
$mbox->send(@grps,$msg);
$mbox->sends(@grps,\%perlhash);
$hashref = $mbox->decode;
$msg_size = $mbox->poll;
$mbox->rx($timeout,@args);
$regular_msg = $mbox->get;
$msg = $mbox->getmsg($timeout);

# Object/Message details
$spread = $mbox->mbox;
@grps = $mbox->grps;
$sent_by = $mbox->sender;
$service_type = $mbox->type;
$message_type = $mbox->mess_type;
$same_endian = $mbox->endian;
$last_message = $mbox->msg;
$last_hashref = $mbox->command;
$is_new_message = $mbox->new_msg;
$time_last_received = $mbox->tm;
$timed_out = $mbox->timeout;
$mysperrorno = $mbox->error;
$whoami = $mbox->me;

# Test message
$mbox->control_msg;
$mbox->aimed_at_me;
$mbox->Is_unreliable_mess;
$mbox->Is_reliable_mess;
$mbox->Is_fifo_mess;
$mbox->Is_causal_mess;
$mbox->Is_agreed_mess;
$mbox->Is_safe_mess;
$mbox->Is_regular_mess;
$mbox->Is_self_discard;
$mbox->Is_reg_memb_mess;
$mbox->Is_transition_mess;
$mbox->Is_caused_join_mess;
$mbox->Is_caused_leave_mess;
$mbox->Is_caused_disconnect_mess;
$mbox->Is_caused_network_mess;
$mbox->Is_membership_mess;
$mbox->Is_reject_mess;
$mbox->Is_self_leave;

# Supplied Callbacks
$mbox->_member_sub
$mbox->_message_sub
$mbox->_error_sub
$mbox->_timeout_sub
$mbox->handle_commands_aimed_at_me

DESCRIPTION

The Spread package provides a simple wrapper around the spread toolkit. We try to provide a much higher level wrapper. By providing:

- Simple methods to send serialised Perl structures between programs
- Callback registration
- Extensible callbacks for command driven programs
- Lots of accesor functions
- Handling of incoming messages is supported via callbacks or
via direct polling for input. Its your choice :-)

OBJECT CONFIGURATION

group => is an array ref of groups to subscribe to
debug => is a scalar variable the effects debugging output
name  => is a scalar variable that defines a Spread name. Must
         be uniq.

The following are the names of the callback config variables. Each
must be a CODE reference.

# These provide message gathering callbacks defined on the type of
# message received.
member_sub   =>  subroutine to handle membership messages.
message_sub  =>  subroutine to hanlde normal data messages
error_sub    =>  gets called when ever we find an error of some kind
timeout_sub  =>  called in the event of any timeout.

# If defined then this installs handle_commands_aimed_at_me() as the
# call back for each of the above and allows you to override bits and
# pieces. See CALLBACKS below
commands     => {
    'default'  => subroutine to handle ALL default message
    'new'      => subroutine to handle 'new' command
    .
    .
}

METHODS

new()

Create a new object and get it configured.

my $mbox = Spread::Message->new(
		name        => $name,
		spread_name => '4803@localhost',
		group       => ['polling-ctl', 'polling-data'],
		member_sub  => \&my_memeber_callback,
		message_sub => \&my_message_callback,
		error_sub   => \&my_error_callback,
		timeout_sub => \&my_timeout_callback,
		debug       => 1,
);
die "Can't create a new message object" unless $mbox;

my $mbox = Spread::Message->new(
		name        => $name,
		spread_name => '4803@localhost',
		group       => ['polling-ctl', 'polling-data'],
		debug       => 1,
		commands    => {
			'default'   => \&myhandlecommands;
		},
);
die "Can't create a new message object" unless $mbox;

configure()

Configure an object before getting connected. You can change the configuration of an object at anytime. But make sure you disconnect and then connect() again afterwards. The new method calls configure for you in the right order. So, normally you wont want to call this method.

However, you may want to, so here is what you can do.

my $mbox = Spread::Message->new(
	name        => $name,
	spread_name => '4803@localhost',
	group       => ['polling-ctl', 'polling-data'],
	member_sub  => \&my_memeber_callback,
	message_sub => \&my_message_callback,
	error_sub   => \&my_error_callback,
	timeout_sub => \&my_timeout_callback,
	debug       => 0,
);
die "Can't create a new message object" unless $mbox;

# stuff happens

# Here we change the membership message call back at run time
$mbox->configure(member_sub => \&new_callback);

# more stuff happens and we eventually disconnect and reconnect
# to a different spread daemon. Same groups and call backs
$mbox->disconnect();
$mbox->configure( spread_name => '4803@newhost' );
$mbox->connect() || warn "Failed to attach to 4803@newhost";

# Change the debugging on the fly
$mbox->configure( debug => 1 );
$mbox->debug(1);

Configure defaults to:

name        => "pid$$"
group       => ['info']
debug       => 0
spread_name => '4803@localhost
member_sub  => sub { print something useful };
message_sub => sub { print something useful };
error_sub   => sub { print something useful };
timeout_sub => sub { print something useful };

You dont have to have callbacks defined. You can still use get() and getmsg() to collect messages. Callbacks are only used when rx() is called.

If you intend to use callbacks and sends() then consider configuring your own command callbacks that will get triggered when a particular command is recieved.

my $mbox = Spread::Message->new(
    name        => $name,
    spread_name => '4803@localhost',
    group       => ['polling-ctl', 'polling-data'],
    commands {
        'default' => \&mysub,
    },
    debug       => 0,
);
die "Can't create a new message object" unless $mbox;

# stuff happens

# Here we change the command control back to the bundled
# handle_commands_aimed_at_me sub.
$mbox->configure(
   commands => { 
     'override' => \&Spread::Message::handle_commands_aimed_at_me
   }
);

connect()

Connect an Spread::Message object to a Spread Daemon and join any groups that have been configured. You almost need to use this method. It is called by you after new() when you first create an object.

$mbox->connect();

You may wish to call this method if you disconnet() and later wish to reconnect to the same or another Spread daemon.

join()

Join any groups that have been configured.

$mbox->join(); # Joins configured groups
$mbox->join('test'); # Joins the test group

Note: connect will join groups configured for you. So don't call join unless you need to.

To find out what groups you have already joined use

my @joined_grps = $mbox->joined;

leave()

Leave one or more groups we have joined previously

$mbox->leave(@grps);

send()

Send a message to set of group/s

$mbox->send(@grps,$msg);

sends()

Send a message to set of group/s

$mbox->sends(@grps,$msg);

Note $msg is run through serialise() so that sends() can be used to send Perl code between processes.

logit()

Send a message to set of logto group/s

$mbox->config( logto => ['a','b'] );
or
$mbox->logto('a','b');

$mbox->logit($msg); # Send the txt message

You set the groups/addresses you want the messages sent to by configuring the logto variable.

The message is formatted such that the process id and hostname are prepended to the message. Much like this:

Tue Jul 29 18:12:20 2003:[19239@localhost] Got status message

decode()

decode a message that has been sent using sends().

my $msg = $mbox->decode() || die "Can't decode';
print "The command is: ", $msg->{'cmd'}, "\n";
print "The structure is: ", Dumper($mbox->command), "\n";

As a side effect the variable $mbox->command() is set to hold the Perl structure returned as a result of the decode.

See FINE GRAINED CALLBACKS below for further details.

disconnect()

Disconnect from the Spread Daemon and reset internal states. The Basic configuration remains however all details of the Spread connection are lost.

$mbox->disconnect();

poll()

Poll to see if there is a new message waiting for picking up. Returns the size of the message waiting.

if($mbox->poll())
{
	#  Have a message to pick up
}
else
{
	#  Have NO message to pick up
}

get()

Pick up the next data message in the queue. get() will loop until a regular data message has been received. It calls getmsg().

# wait for a data message - this could be a while
my $msg = $mbox->get();

rx()

receive next bunch of messages and trigger any call backs as required. Also pass all other arguments to any called routines.

$mbox->rx($timeout,"loop 20");

Will have rx wait for $timeout seconds and call any of the defined callback methods with a copy of $mbox and "loop 20" in this example.

Every callback function can expect to receive at least one paramater which is a copy of the mbox and then any further paramters as defined in the call to rx.

rx will return whatever the callback returns.

getmsg()

get the next mesage from our queue and set the current state details accordingly. All the ACCESSOR functions below will be updated.

my $msg = $mbox->getmsg($timeout)

or

$mbox->getmsg($timeout);
my $msg = $mbox->msg;

or

$mbox->getmsg($timeout);
if($mbox->new_msg)
{
	my $msg = $mbox->msg;
}

getmsg will return the next message only if there is one to return. Otherwise it returns a null string.

With debugging turned on getmsg will also print details of messages received.

ACCESSORS

mbox() - return the current Spread Mailbox connection id

grps() - return the current groups the last message was sent to

joined() - return the current groups we have joined succesfully

logto() - return the current groups we will log to

sender() - return the sender of the last message.

type() - return the service type of the last message.

mess_type() - return the message type of the last message.

reason() - return the reason we got the last message

"$who joining"
"$who leaving"
"$who disconnecting"
"Network change"
'Transition for group '.$self->sender
'membership message that left group '.$self->sender
'Reject from '.$self->sender
"regular message"
"Error unknown message"

endian() - return true if the last message has same endian

msg() - return the last message.

command() - return the last Perl structure decoded using the decode() method.

new_msg() - return true if the last message was a new message indicates and error when false

tm() - return the time the last message was received

timeout() - did the last rx() call time out?

error() - return the last error as defined by Spread sperror

me() - return my name as Spread knows it. This is needed to work out if a message was sent to me directly rather than via a group. It is effectively my private group name.

spread_name() - return the Spread daemon details

name() - return our defined name used when we first connected.

debug() - return our debug level

control_msg() - Is the current message a control message for me.

That is, does this message eminate from a .*-ctl group that I am joined to OR is it directed specifically at me.

aimed_at_me - Is the previous message aimed specifically at me

These methods return details of the current message. See the Spread documentation for further details.

Is_unreliable_mess()
Is_reliable_mess()
Is_fifo_mess()
Is_causal_mess()
Is_agreed_mess()
Is_safe_mess()
Is_regular_mess()
Is_self_discard()
Is_reg_memb_mess()
Is_transition_mess()
Is_caused_join_mess()
Is_caused_leave_mess()
Is_caused_disconnect_mess()
Is_caused_network_mess()
Is_membership_mess()
Is_reject_mess()
Is_self_leave()

CALLBACKS

Some very simple call back are provided. You should override these when calling new().

They basically print out a little information and then return. These are defined as:

Spread::Message::_member_sub

Spread::Message::_message_sub

Spread::Message::_error_sub

Spread::Message::_timeout_sub

You can use them if you like. But I wouldn't :-)

FINE GRAINED CALLBACKS

Some fine grained callback subs are provided that you can extend. This makes creating Message programms a little easier. We provide a simple command interpreter that can handle commands sent to us using the sends method. It assumes the messages sent are done in this form:

%msg = (
	cmd   => 'some sort of command',
	.
	.
);

The only requirement is that the hashref sent to sends() has a key called cmd, and that cmd contains a valid command name to call. Also, you must sends() the message to a specific Spread user not to a group. That is, aimed_at_me() must return true when the message is received.

We automatically handle commands where cmd is:

shut or stop or die    => program dies
restart                => program restarts itself
clone                  => program creates another copy of self
status                 => program sends() status info

It assumes you have defined a 'default' function. If not then a message is printed.

You can define your own commands to override the ones we provide. Or you can provide a single 'override' function. This is done like this:

In the receiving application:

use Data::Dumper;

sub new 
{ 
    # We get the Spread::Message object and any args sent to rx()
    my($mbox,@args) = @_;

    # pick up decode command
    my %msg = %{$mbox->command};
    
    print "new() called with args @args\n"; 
    print "and message >",$mbox->msg,"<\n";
}

sub mydefault 
{ 
    # We get the Spread::Message object and any args sent to rx()
    my($mbox,@args) = @_;

    # pick up decoded command
    my %msg = %{$mbox->command};
    
    print "mydefault() called with args @args\n"; 
    print "and message >",$mbox->msg,"<\n";
}

my $mbox = Message->new(
    .
    .
    name  => "fping$$",
    group => ['polling-ctl', 'polling-data'],
    .
    # This says use the fine grained commands
    commands    => {
        'new'       => \&new,       # handle 'new' commands
        'default'   => \&mydefault, # handle left over commands

        # Only define this if you want to catch ALL the commands
        #'override'  => \&myoverride,
    },
    .
    .
);

while(1)
{
    # Process different data as required
    $mbox->rx(30,'arg1','arg2');
}

In the sending application:

sub process_control
{
    my $mbox = shift;

    # A global array to hold stuff
    @Settings::pingers = grep(/fping/,$mbox->grps);
}

my $mbox = Message->new(
    .
    group => ['polling-ctl', 'polling-data'],
    member_sub  => \&process_control,
    .
);

my %msg = (
    cmd   => 'new'
    .
    .
);

# Use rx() to receive any membership messages and make sure you snarf
# away the id of the receiving application. Should exist in
# @Settings::pingers once a receiving application has joined a group
# of ours
$mbox->rx(30,undef);
my $id = shift(@Settings::pingers);

$mbox->sends($id,\%msg);   # Send new command specifically to $id
$msg{'cmd'} = 'restart';
$mbox->sends($id,\%msg);   # Send restart command specifically to $id
$msg{'cmd'} = 'funny';
$mbox->sends($id,\%msg);   # Send funny command, will call default
$msg{'cmd'} = 'clone';
$mbox->sends($id,\%msg);   # Send clone command specifically to $id
$msg{'cmd'} = 'stop';
$mbox->sends($id,\%msg);   # Send stop command specifically to $id

Bugs and other stuff

There are bound to be bugs in this code. It is first cut code that even though used extensively hasn't been used broadly. By that I mean, the bits of this code that I have used, works well for me, but my use isn't your use, and you may stumble across bugs.

If you do find bugs, then please go to the effort of reporting it in a manner in which I can get a good understanding of what your talking about.

Please note: I have no affiliation with The Spread Group Communication Toolkit. I also know next to nothing about messaging and group communication, so dont' ask me about these things.

This module is offered in good faith as is.

TODO

Lots-n-lots

Copyright

This code may be copied only under the terms of the Artistic License or the GNU General Public License, version 2 or later which may be found in the Perl 5 source kit.

Use 'perldoc perlartistic' to see the Artistic License. Use 'perldoc perlgpl' to see the GPL License.

Complete documentation for Perl, including FAQ lists, should be found on this system using `man perl' or `perldoc perl'. If you have access to the Internet, point your browser at http://www.perl.org/, the Perl Home Page.

To install Spread::Message, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Spread::Message

CPAN shell

perl -MCPAN -e shell
install Spread::Message

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)