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.