POE::Component::IKC::Responder - POE IKC state handler
use POE; use POE::Component::IKC::Responder; create_ikc_responder(); ... $kernel->post('IKC', 'post', $to_state, $state); $ikc->publish('my_name', [qw(state1 state2 state3)]);
This module implements an POE IKC state handling. The responder handles posting states to foreign kernels and calling states in the local kernel at the request of foreign kernels.
There are 2 interfaces to the responder. Either by sending states to the 'IKC' session or the object interface. While the latter is faster, the better behaved, because POE is a cooperative system.
post
Sends an state request to a foreign kernel. Returns logical true if the state was sent and logical false if it was unable to send the request to the foreign kernel. This does not mean that the foreign kernel was able to post the state, however. Parameters are as follows :
foreign_state
Specifier for the foreign state. See POE::Component::IKC::Specifier.
parameters
A reference to anything you want the foreign state to get as ARG0. If you want to specify several parameters, use an array ref and have the foreign state dereference it.
$kernel->post('IKC', 'post', {kernel=>'Syslog', session=>'logger', state=>'log'}, [$faculty, $priority, $message];
or
$ikc->post('poe://Syslog/logger/log', [$faculty, $priority, $message]);
This logs an state with a hypothetical logger.
call
This is identical to post, except it has a 3rd parameter that describes what state should receive the return value from the foreign kernel.
$kernel->post('IKC', 'call', 'poe://Pulse/timeserver/time', '', 'poe:get_time');
$ikc->call({kernel=>'Pulse', session=>'timeserver', state=>'time'}, '', 'poe:/me/get_time');
This asks the foreign kernel 'Pulse' for the time. 'get_time' state in the current session is posted with whatever the foreign state returned.
Identical to the post foreign_state parameter.
Identical to the post parameters parameter.
rsvp
Event identification for the callback. That is, this state is called with the return value of the foreign state. Can be a foreign_state specifier or simply the name of an state in the current session.
$kernel->call('IKC', 'post', {kernel=>'e-comm', session=>'CC', state=>'check'}, {CC=>$cc, expiry=>$expiry}, folder=>$holder}, 'is_valid'); # or $ikc->call('poe:/e-comm/CC/check', {CC=>$cc, expiry=>$expiry}, folder=>$holder}, 'poe:/me/is_valid');
This asks the e-comm server to check if a credit card number is "well formed". Yes, this would probably be massive overkill.
The rsvp state does not need to be published. IKC keeps track of the rsvp state and will allow the foreign kernel to post to it.
default
Sets the default foreign kernel. You must be connected to the foreign kernel first.
Unique parameter is the name of the foreign kernel kernel.
Returns logical true on success.
register
Registers foreign kernel names with the responder. This is done during the negociation phase of IKC and is normaly handled by IKC::Channel. Will define the default kernel if no previous default kernel exists.
IKC::Channel
Unique parameter is either a single kernel name or an array ref of kernel names to be registered.
unregister
Unregisters one or more foreign kernel names with the responder. This is done when the foreign kernel disconnects by IKC::Channel. If this is the default kernel, there is no more default kernel.
Unique parameter is either a single kernel name or an array ref of kernel names to be unregistered.
publish
Tell IKC that some states in the current session are available for use by foreign sessions.
session
A session alias by which the foreign kernels will call it. The alias must already have been registered with the local kernel.
states
Arrayref of states that foreign kernels may post.
$kernel->post('IKC', 'publish', 'me', [qw(foo bar baz)]); # or $ikc->publish('me', [qw(foo bar baz)]);
retract
Tell IKC that some states should no longer be available for use by foreign sessions. You do not have to retract all published states.
Same as in publish
$kernel->post('IKC', 'retract', 'me', [qw(foo)]); # or $ikc->retract('me', [qw(foo)]);
subscribe
Subscribe to foreign sessions or states. When you have subscribed to a foreign session, a proxy session is created on the local kernel that will allow you to post to it like any other local session.
specifiers
An arrayref of the session or state specifiers you wish to subscribe to. While the wildcard '*' kernel may be used, only the first kernel that acknowledges the subscription will be proxied.
callback
Either an state (for the state interface) or a coderef (for the object interface) that is posted (or called) when all subscription requests have either been replied to, or have timed out.
When called, it has a single parameter, an arrayref of all the specifiers that IKC was able to subscribe to. It is up to you to see if you have enough of the foreign sessions or states to get the job done, or if you should give up.
While callback isn't required, it makes a lot of sense to use it because it is only way to find out when the proxy sessions become available.
Example :
$ikc->subscribe([qw(poe://Pulse/timeserver)], sub { $kernel->post('poe://Pulse/timeserver', 'connect') });
(OK, that's a bad example because we don't check if we actually managed to subscribe or not.)
$kernel->post('IKC', 'subscribe', [qw(poe://e-comm/CC poe://TouchNet/validation poe://Cantax/JDE poe://Informatrix/JDE) ], 'poe:subscribed', ); # and in state 'subscribed' sub subscribed { my($kernel, $specs)=@_[KERNEL, ARG0]; if(@$specs != 4) { die "Unable to find all the foreign sessions needed"; } $kernel->post('poe://Cantax/JDE', 'write', {...somevalues...}); }
This is a bit of a mess. You might want to use the subscribe parameter to create_ikc_client instead.
create_ikc_client
Subscription receipt timeout is currently set to 120 seconds.
unsubscribe
Reverse of the subscribe method. However, it is currently not implemented.
create_ikc_responder
This function creates the Responder session and object. However, you don't need to call this directly, because IKC::Client or IKC::Server does this for you.
IKC::Client
IKC::Server
Sending session references and coderefs to a foreign kernel is a bad idea :) At some point it would be desirable to recurse through the paramerters and and turn any session references into state specifiers.
rsvp state in call is a bit problematic. IKC allows it to be posted to once, but doesn't check to see if the foreign kernel is the right one.
retract does not currently tell foreign kernels that have subscribed to a session/state that it has been retracted.
call()ing a state in a proxied foreign session doesn't work, for obvious reasons.
call()ing
Philip Gwyn, <fil@pied.nu>
POE, POE::Component::IKC::Server, POE::Component::IKC::Client
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install POE::Component::IKC::Proxy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::IKC::Proxy
CPAN shell
perl -MCPAN -e shell install POE::Component::IKC::Proxy
For more information on module installation, please visit the detailed CPAN module installation guide.