NAME

Spread::Client - Spread client that allows synchronous OR asynchronous multicast/receive/join/leave/disconnect to spread daemons

SYNOPSIS

  # ASYNCHRONOUS AnyEvent BEHAVIOR(with POE)
  use strict;
  use warnings;
  use POE;
  use Spread::Client;
  use Spread::Client::Constant ':all'; 
  use Danga::Socket;
  use Data::Dumper;
  
  my $spread_name = '4803@localhost';
  my $private_name = 'mrperla';
  
  
  # set message count before exit
  my $message_max = 10;
  my $message_count = 0;
  
  # Connect using Danga socket connection class for 
  # running with Danga::Socket Event loop
  my $conn = Spread::Client::connect(
        spread_name   => $spread_name,
        private_name  => $private_name,
        connect_class => 'Async::AnyEvent',
     );
  
  # set callback to handle message receipts
  $conn->message_callback( \&handle_message );
  
  Spread::Client::join( conn   => $conn,
                        groups => ['channel-100'],
                      );
  
  # If you decide not to give this message a 'type'
  # then it will default to sending a RELIABLE MESSAGE
  Spread::Client::multicast( conn    => $conn,
                             groups  => ['channel-100'],
                             message => 'this is a message',
                           );

  sub handle_message {
      my ($conn, @message) = @_;
  
      print Dumper( \@message );
  
      $message_count++;
  
      if( $message_count >= $message_max ) {
  
          Spread::Client::leave( conn   => $conn,
                                 groups => ['channel-100'],
                              );
  
          Spread::Client::disconnect( conn => $conn );
          POE::Kernel->stop();
      }
  }

  # Don't forget to start your event loop  
  POE::Kernel->run();

  # ASYNCHRONOUS DANGA BEHAVIOR
  use strict;
  use warnings;
  use Spread::Client;
  use Spread::Client::Constant ':all';
  use Danga::Socket;
  use Data::Dumper;
  
  my $spread_name = '4803@localhost';
  my $private_name = 'mrperla';
  
  
  # set message count before exit
  my $message_max = 10;
  my $message_count = 0;
  
  # Connect using Danga socket connection class for 
  # running with Danga::Socket Event loop
  my $conn = Spread::Client::connect(
        spread_name   => $spread_name,
        private_name  => $private_name,
        connect_class => 'Async::Danga',
     );
  
  # set callback to handle message receipts
  $conn->message_callback( \&handle_message );
  
  Spread::Client::join( conn   => $conn,
                        groups => ['channel-100'],
                      );
  
  # If you decide not to give this message a 'type'
  # then it will default to sending a RELIABLE MESSAGE
  Spread::Client::multicast( conn    => $conn,
                             groups  => ['channel-100'],
                             message => 'this is a message',
                           );

  sub handle_message {
      my ($conn, @message) = @_;
  
      print Dumper( \@message );
  
      $message_count++;
  
      if( $message_count >= $message_max ) {
  
          Spread::Client::leave( conn   => $conn,
                                 groups => ['channel-100'],
                              );
  
          Spread::Client::disconnect( conn => $conn );
          Danga::Socket->SetPostLoopCallback( sub { 0 } );
      }
  }
  # Don't forget to start your event loop  
  Danga::Socket->EventLoop();

  # SYNCHRONOUS BEHAVIOR
  use strict;
  use warnings;
  use Spread::Client;
  use Spread::Client::Constant ':all';
  use Data::Dumper;
  
  my $spread_name = '4803@localhost';
  my $private_name = 'mrperls';
  
  # Connect using Sync class
  # if connect_class is left out, defaults to 'Sync'
  my $conn = Spread::Client::connect(
        spread_name   => $spread_name,
        private_name  => $private_name,
        connect_class => 'Sync',
     );
  
  # If we need the private group
  my $private_group = $conn->private_group;
  
  Spread::Client::join( conn   => $conn,
                        groups => ['channel-100'],
                      );
  
  Spread::Client::multicast( conn    => $conn,
                             type => SAFE_MESS,
                             groups  => ['channel-100'],
                             message => 'this is a message',
                           );
  
  for (1..2) {
  
      my ($service_type, $sender, $groups, $mess_type, $endian, $message) =
      Spread::Client::receive( conn  => $conn );

      # Should Dump a join message, and our multi-cast since SELF_DISCARD isn't on
      warn Dumper( $service_type, $sender, $groups, $mess_type, $endian, $message);
  }
  
  # leave group
  Spread::Client::leave( conn   => $conn,
                         groups => ['channel-100'],
                       );

  # disconnect
  Spread::Client::disconnect( conn => $conn );

DESCRIPTION

A Spread Toolkit client implemented in perl, that allows both synchronous and asynchronous functionality. Reading the Spread User's Guide is strongly recommended before using the Spread Toolkit in general.

CAVEATS

Right now connect is always synchronous, this may change later but unless someone really wants it i don't see it occuring anytime soon. Asynchronous is supported for Danga::Socket and AnyEvent which should cover a large number of the event loops out there, include POE. If you would like to use AnyEvent or Danga, please have them installed, it's not a prerequisite of the module as connection classes are loaded at runtime and the synchronous connection client does not depend on either Danga::Socket or AnyEvent.

EXPORT

None by default.

SEE ALSO

Constants module Spread::Client::Constant.

Without these helpful sources, this module would not have been possible:

Rough spread API, documented by a nice developer. http://www.roughtrade.net/spread/spread-client-proto.txt

Pure Python Spread Client http://code.google.com/p/py-spread/

Spread source including their C and JAVA client http://www.spread.org/

AUTHOR

Marlon Bailey, <mbailey@span.org<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Marlon Bailey

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.8 or, at your option, any later version of Perl 5 you may have available.