NAME

POE::Component::Lightspeed::Introspection - Discovering your network!

SYNOPSIS

        use POE;
        use POE::Component::Lightspeed::Client;
        use POE::Component::Lightspeed::Server;
        use POE::Component::Lightspeed::Introspection qw( list_kernels list_sessions list_states );

        # Spawn your client/server session here and connect to the network

        # Find out the kernels in the network
        my $kernels = list_kernels();
        print "Kernels:", join( " ,", @$kernels );

        # Query a specific kernel for it's sessions
                # Remember, we need a RSVP specifier here
                list_sessions( 'kernel1', 'poe://mykernel/mysession/got_sessions' );

                # This rsvp will get 2 events, one from each kernel it queried
                list_sessions( [ qw( kernel1 kernel2 ) ], 'poe://mykernel/mysession/got_sessions' );

                # Inside an event handler where $_[SENDER] is a remote kernel
                list_sessions( $_[SENDER], 'poe://mykernel/mysession/got_sessions' );

        # Query a specific kernel / session for it's states
                # Basically, this accepts the full destination specifier, only without the state parameter
                list_states( 'poe://kernel1/mysession', 'poe://mykernel/mysession/got_states' );

                # This is also allowed
                list_states( [ [ qw( kernel1 kernel2 ) ], 'mysession' ], 'poe://mykernel/mysession/got_states' );

                # Madness, madness!
                list_states( { 'KERNEL' => '*', 'SESSION' => '*' }, 'poe://mykernel/mysession/got_states' );

                # Inside an event handler where $_[SENDER] is a remote kernel
                list_states( $_[SENDER], 'poe://mykernel/mysession/got_states' );

ABSTRACT

        This module presents an easy API for finding information about the network.

DESCRIPTION

All you need to do is import the 3 subroutines provided.

METHODS

list_kernels

        Requires no arguments

        Returns an arrayref of kernel names

list_sessions

        Requires two arguments
                - The kernel name to query
                        Can be a scalar with the kernel name, or '*'
                        Can be an arrayref full of kernel names
                        Can be $_[SENDER] when it's a remote kernel

                - The RSVP to send the results
                        Must be a fully-qualified destination specifier as explained in the Lightspeed docs

        NOTE: This will return every alias a session has, not only the first alias!

        Returns nothing, the data will be sent to the RSVP
                ARG0 = kernel name
                ARG1 = arrayref of sessions
                        Example:
                                [
                                        [       'mysession',
                                                'secondalias',
                                                'thirdalias',
                                        ],
                                        [       'weeble',
                                        ],
                                        [       'frobnicate',
                                        ]
                                ]

list_states

        Requires two arguments
                - The kernel/session to query
                        Can be a fully-qualified destination specifier without the state, i.e. 'poe://kernel/session'
                        Can be an arrayref as explained in the Lightspeed docs, without the 3rd element set
                        Can be a hashref with the KERNEL and SESSION keys
                        Can be $_[SENDER] when it's a remote kernel

                - The RSVP to send the results
                        Must be a fully-qualified destination specifier as explained in the Lightspeed docs

        NOTE: This will return only one alias per session, to avoid confusion over duplicate aliases

        Returns nothing, the data will be sent to the RSVP
                ARG0 = kernel name
                ARG1 = hashref of sessions -> array of states
                        Example:
                                {
                                        'mysession'     =>      [       '_stop',
                                                                        '_default',
                                                                        'mystate',
                                                                        'mystate2',
                                                                ],
                                        'othersession'  =>      [       'floo',
                                                                        'bar',
                                                                ]
                                }

EXPORT

Exports the 3 subs in EXPORT_OK

SEE ALSO

POE::Component::Lightspeed

AUTHOR

Apocalypse <apocal@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 by Apocalypse

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