Apocalypse

NAME

POE::Component::SpreadClient - Handle Spread communications in POE

SYNOPSIS

        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?' );
        }

DESCRIPTION

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 )

XXX Beware: this module hasn't been tested with Spread 4! XXX

METHODS

spawn

        POE::Component::Spread->spawn( 'spread' );

        - The alias the component will take ( default: "SpreadClient" )

        Returns the session ID.

Public API

connect

        $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

disconnect

        $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

subscribe

        $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

unsubscribe

        $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

publish

        $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

register

        $poe_kernel->post( spread => register );

        Registers the current session as a "registered listener" and will receive all events.

unregister

        $poe_kernel->post( spread => unregister );

        Removes the current session from the "registered listeners" list.

destroy

        $poe_kernel->post( spread => destroy );

        Destroys the session by removing it's alias and disconnecting if needed with C<_sp_disconnect>

EVENTS

_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
        }

SpreadClient Notes

You can enable debugging mode by doing this:

        sub POE::Component::SpreadClient::DEBUG () { 1 }
        use POE::Component::SpreadClient;

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc POE::Component::SpreadClient

Websites

Bugs

Please report any bugs or feature requests to bug-poe-component-spreadclient at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-SpreadClient. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

Spread

Spread::Message

POE::Component::Spread

AUTHOR

Apocalypse <apocal@cpan.org>

The base for this module was lifted from POE::Component::Spread by Rob Partington <perl-pcs@frottage.org>.

COPYRIGHT AND LICENSE

Copyright 2009 by Apocalypse

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.