NAME

Spread::Session - OO wrapper for Spread messaging toolkit

SYNOPSIS

  use Spread::Session;

  my $session = new Spread::Session(
                        MESSAGE_CALLBACK => \&message_callback,
                        ADMIN_CALLBACK   => sub {},
                                   );

  $session->subscribe("mygroup");
  $session->publish("othergroup", $message);

  $session->receive($timeout, $extra_param);

  sub message_callback {
    my ($message_info, $extra_param) = @_;
    # do something
    return $message_info->{BODY};
  }

DESCRIPTION

Wrapper module for Spread.pm, providing an object-oriented interface to the Spread messaging toolkit. The existing Spread.pm package is a straightforward functional interface to the Spread C API.

A session represents a connection to a Spread messaging daemon. The publish and subscribe functions are for communication via spread groups.

Handling of incoming messages is supported via callbacks; the receive() method does not directly return the incoming message parameters to the calling code.

METHODS

Most methods check the value of the Spread error code, $sperrno, and will die() if this value is set.

new

  my $session = new Spread::Session(private_name => 'foo',
                                    spread_name => '4444@remotenode',
        #optional                   MESSAGE_CALLBACK => \&my_msg_callback,
        #optional                   ADMIN_CALLBACK => \&my_admin_callback,
        #optional                   TIMEOUT_CALLBACK => \&my_timeout_callback,
        #optional                   TIMEOUT => 5,
                                   );

Establish a connection to a Spread messaging daemon at the host and port specified in the 'spread_name' parameter. Default value is 4803@localhost.

If 'private_name' is not provided, Spread will generate a unique private address based on process id and hostname. If a value is provided for this parameter, you must ensure uniqueness.

Provided MESSAGE_CALLBACK and ADMIN_CALLBACK coderefs will be invoked with a reference to a hash containing the components of the incoming message in fields named SERVICE_TYPE, SENDER, GROUPS (arrayref), MESSAGE_TYPE, ENDIAN, and BODY. A reference back to the Spread::Session object is provided in SESSION. Any other parameters provided in the receive() method call will be passed through to the callback as well.

The TIMEOUT parameter overrides the built-in 5-second default timeout for the receive() call.

callbacks - DEPRECATED

  $session->callbacks(message => \&message_callback,
                      admin => \&admin_callback,
                      timeout => \&timeout_callback);

Define application callback functions for regular inbound messages on subscribed groups, administrative messages regarding subscribed groups (e.g. membership events), and timeouts (cf. receive).

If no value is provided for any one of these events, a trivial stub is provided by Spread::Session.

subscribe

  $session->subscribe("mygroup", ...);

Inform Spread that a copy of any message published to the named group(s) should be dispatched to this process.

publish

  $session->publish("othergroup", $message);

Transmit a message to the specified group.

$message is assumed to be a string; serialization of other data types is not provided here.

poll

  my $msize = $session->poll;

Non-blocking check to see if a message is available on any subscribed group (including this session's private mailbox). Returns the size of the first pending message. A zero indicates no message is pending.

receive

  $session->receive($timeout, $args...);

Waits for $timeout seconds for a message to arrive on any subscribed group (including this session's private mailbox). If a regular message arrives, it is delivered to the message callback defined above. If a Spread administrative message arrives (e.g. a group membership notification), it is transmitted to any admin callback that has been installed. If no message arrives, the timeout callback is called, if any.

Additional optional parameters may be provided to receive(). These will be passed along to the callback routines.

CALLBACKS

  sub my_message_callback {
    my ($sender, $groups, $message, @args) = @_;
  }

  sub my_admin_callback {
    my ($service_type, $sender, $groups, $message, @args) = @_;
  }

  sub my_timeout_callback {
    my (@args) = @_;
  }

Some trivial default callbacks (dump incoming message details to stdout) are provided by Spread::Session. Your application should override all of these.

err

  my $sperrno = $session->err;

Retrieve the value of the current Spread error, if any.

AUTHOR

Jason W. May <jmay@pobox.com>

Joshua Goodall <joshua@roughtrade.net> maintains the FreeBSD package for this module.

COPYRIGHT

Copyright (C) 2002 Jason W. May. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The license for the Spread software can be found at http://www.spread.org/license

SEE ALSO

  L<Spread>
  L<Log::Channel>