POE::Component::SpreadClient - handle Spread communications in POE
POE::Component::SpreadClient->spawn( 'spread' ); POE::Session->create( inline_states => { _start => \&_start, _sp_message => \&do_something, _sp_admin => \&do_something, _sp_connect => \&do_something, _sp_disconnect => \&do_something, _sp_error => \&do_something, } ); sub _start { $poe_kernel->alias_set('displayer'); $poe_kernel->post( spread => connect => 'localhost', $$ ); $poe_kernel->post( spread => subscribe => 'chatroom' ); $poe_kernel->post( spread => publish => 'chatroom', 'A/S/L?' ); }
POE::Component::SpreadClient is a POE component for talking to Spread servers.
This module should only be used with Spread 3.17.3 ( or compatible versions )
POE::Component::Spread->spawn( 'spread' ); - The alias the component will take ( default: "SpreadClient" )
$poe_kernel->post( spread => connect => '4444@localhost' ); $poe_kernel->post( spread => connect => '4444@localhost', 'logger' ); - The Server location - The private name for the Spread connection ( default: "spread-PID" ) Connect this POE session to the Spread server on port 4444 on localhost. Will send a C<_sp_error> event if unable to connect; C<_sp_connect> if successful
$poe_kernel->post( spread => disconnect ); Forces this session to disconnect. ( DOES NOT REMOVE ALIAS => look at destroy below ) Will send a C<_sp_disconnect> event if disconnected; C<_sp_error> if failure
$poe_kernel->post( spread => subscribe => 'chatroom' ); $poe_kernel->post( spread => subscribe => [ 'chatroom', 'testing' ] ); - The group name(s) Subscribe to a Spread messaging group. Messages will be sent to C<_sp_message> and join/leave/etc to C<_sp_admin> in the registered listeners. Automatically adds the session to the registered listeners. Will send a C<_sp_error> if unable to subscribe; C<_sp_admin> with join message if successful
$poe_kernel->post( spread => unsubscribe => 'chatroom' ); $poe_kernel->post( spread => unsubscribe => [ 'foobar', 'chatroom' ] ); Unsubscribes to a Spread messaging group. Does not remove the session from the listener list. Will send a C<_sp_error> if unable to unsubscribe; C<_sp_admin> with self_leave if successful
$poe_kernel->post( spread => publish => 'chatroom', 'A/S/L?' ); $poe_kernel->post( spread => publish => [ 'chatroom', 'stats' ], 'A/S/L?' ); $poe_kernel->post( spread => publish => 'chatroom', 'special', 5 ); $poe_kernel->post( spread => publish => 'chatroom', 'A/S/L?', undef, RELIABLE_MESS & SELF_DISCARD ); - The group name(s) - 2nd parameter ( int ) is the Spread mess_type -> application-defined ( default: 0 ) - The 3rd parameter is the spread message type -> import them from Spread.pm ( default: SAFE_MESS ) Send a string to the group(s). THIS WILL ONLY SEND STRINGS! If you need to send perl structures, use your own serializer/deserializer! REMEMBER about the message size limitation From spread-src-3.17.3 #define MAX_MESSAGE_BODY_LEN (MAX_SCATTER_ELEMENTS * (MAX_PACKET_SIZE - 32)) /* 32 is sizeof(packet_header) */ #define MAX_SCATTER_ELEMENTS 100 #define MAX_PACKET_SIZE 1472 /*1472 = 1536-64 (of udp)*/ Therefore max message size is 100 * 1440 =~ 140kB Will send a C<_sp_error> if unable to publish
$poe_kernel->post( spread => register ); Registers the current session as a "registered listener" and will receive all events.
$poe_kernel->post( spread => unregister ); Removes the current session from the "registered listeners" list.
$poe_kernel->post( spread => destroy ); Destroys the session by removing it's alias and disconnecting if needed with C<_sp_disconnect>
_sp_connect
sub _sp_connect : state { my( $priv_name, $priv_group ) = @_[ ARG0, ARG1 ]; # We're connected! }
_sp_disconnect
sub _sp_disconnect : state { my $priv_name = $_[ ARG0 ]; # We're disconnected! }
_sp_error
sub _sp_error : state { my( $priv_name, $type, $sperrno, $msg, $data ) = @_[ ARG0 .. ARG4 ]; # Handle different kinds of errors if ( $type eq 'CONNECT' ) { # $sperrno = Spread errno/error string, $msg = server name, $data = priv name } elsif ( $type eq 'PUBLISH' ) { # $sperrno = Spread errno, $msg = $groups ( may be undef ), $data = $message ( may be undef ) } elsif ( $type eq 'SUBSCRIBE' ) { # $sperrno = Spread errno, $msg = $groups ( may be undef ) } elsif ( $type eq 'UNSUBSCRIBE' ) { # $sperrno = Spread errno, $msg = $groups ( may be undef ) } elsif ( $type eq 'RECEIVE' ) { # $sperrno = error string } }
_sp_message
sub _sp_message : state { my( $priv_name, $sender, $groups, $mess_type, $message ) = @_[ ARG0 .. ARG4 ]; # $mess_type is always 0 unless defined ( mess_type in Spread ) }
_sp_admin
sub _sp_admin : state { my( $priv_name, $data ) = @_[ ARG0, ARG1 ]; # $data is hashref with several fields: # TYPE => string ( JOIN | LEAVE | DISCONNECT | SELF_LEAVE | TRANSITIONAL | NETWORK ) # GROUP => string ( group name ) # GID => [ GID1, GID2, GID3 ] ( look at Spread documentation about this! ) # MEMBERS => arrayref of member names # WHO => string ( whomever left/join/discon ) # INDEX => index of self in group list # MESSAGE => raw unpacked message ( needed for NETWORK's special parsing, not done! ) # if TYPE = JOIN | LEAVE | DISCONNECT # GROUP, MEMBERS, WHO, GID, INDEX # if TYPE = SELF_LEAVE # GROUP # if TYPE = TRANSITIONAL # GROUP # if TYPE = NETWORK # GROUP, MEMBERS, GID, INDEX, MESSAGE }
You can enable debugging mode by doing this:
sub POE::Component::SpreadClient::DEBUG () { 1 } use POE::Component::SpreadClient;
- Need to be tested more! - Endian mis-match is simply a warn, should it be added to _sp_message ?
Spread
Spread::Message
POE::Component::Spread
The base for this module was lifted from POE::Component::Spread by Rob Partington <perl-pcs@frottage.org>.
Copyright 2006 by Apocalypse
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install POE::Component::SpreadClient, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::SpreadClient
CPAN shell
perl -MCPAN -e shell install POE::Component::SpreadClient
For more information on module installation, please visit the detailed CPAN module installation guide.