Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IKC::Responder(3)     User Contributed Perl Documentation    IKC::Responder(3)

NAME
       POE::Component::IKC::Responder -	POE IKC	state handler

SYNOPSIS
	   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)]);

DESCRIPTION
       This module implements 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.

STATES/METHODS
   "spawn"
	   POE::Component::IKC::Responder->spawn();

       This function creates the Responder session and object.	Normally,
       POE::Component::IKC::Client or POE::Component::IKC::Server does this
       for you.	 But in	some applications you want to make sure	that the
       Responder is up and running before then.

   "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.

       See the "PROXY SENDER" below.

   "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');

       or

	   $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.

       You do not have to publish callback messages, because they are
       temporarily published.  How temporary?  They can	be posted from a
       remote kernel ONCE only.	 This, of course, is a problem because someone
       else could get in a post	before the callback.  Such is life.

       "foreign_state"
	  Identical to the "post" "foreign_state" parameter.

       "parameters"
	  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.

       See the "PROXY SENDER" below.

   "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.

       First parameter is either a single kernel name.	Second optional
       parameter is an array ref of kernel aliases to be registered.

   "unregister"
       Unregisters one or more foreign kernel names with the responder.	 This
       is done when the	foreign	kernel disconnects by
       POE::Component::IKC::Channel.  If this is the default kernel, there is
       no more default kernel.

       First parameter is either a single kernel name or a kernel alias.
       Second optional parameter is an array ref of kernel aliases to be
       unregistered.  This second parameter is a tad silly, because if you
       unregister a remote kernel, it goes without saying that all it's
       aliases get unregistered	also.

   "register_local"
       Registers new aliases for local kernel with the responder.  This	is
       done internally by POE::Component::IKC::Server and
       POE::Component::IKC::Client. Will NOT define the	default	kernel.

       First and only parameter	is an array ref	of kernel aliases to be
       registered.

   "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.

       "session"
	 Same as in "publish"

       "states"
	 Same as in "publish".	If not supplied, *all* published states	are
	 retracted.

	     $kernel->post('IKC', 'retract', 'me', [qw(foo mibble dot)]);
	     # or
	     $ikc->retract('me', [qw(foo)]);

   "published"
	   $list=$kernel->call(IKC=>'published', $session);

       Returns a list of all the published states.

	   $hash=$kernel->call(IKC=>'published');

       Returns a hashref, keyed	on session IDs.	 Values	are arrayref of	states
       published by that session.

       "session"
	 A session alias that you wish the list	of states for.

   "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 a 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 "spawn" instead.

	  Subscription receipt timeout is currently set	to 120 seconds.

   "unsubscribe"
       Reverse of the "subscribe" method.  However, it is currently not
       documented well.

   "ping"
       Responds	with 'PONG'.  This is auto-published, so it can	be called from
       remote kernels to see if	the local kernel is still around.  In fact, I
       don't see any other use for this.

	   $kernel->post('poe://remote/IKC', 'ping', 'some_state');
	   $kernel->delay('some_state',	60);   # timeout

	   sub some_state
	   {
	       my($pong)=$_[ARG0];
	       return if $pong;		   # all is cool

	       # YOW!  Remote kernel timed out.	 RUN AROUND SCREAMING!
	   }

   "shutdown"
       Hopefully causes	IKC and	all peripheral sessions	to dissapear in	a puff
       of smoke.  At the very least, any sessions left will be either not
       related to IKC or barely	breathing (that	is, only have aliases keeping
       them from GC).  This should allow you to	sanely shut down your process.

   "monitor"
       Allows a	session	to monitor the state of	remote kernels.	 Currently, a
       session is informed when	a remote kernel	is registered, unregistered,
       subscribed to or	unsubscribed from.  One	should make sure that the IKC
       alias exists before trying to monitor.  Do this by calling
       POE::Component::IKC::Responder->spawn or	in an "on_connect" callback.

	   $kernel->post('IKC',	'monitor', $remote_kernel_id, $states);

       $remote_kernel_id
	  Name or alias	or IKC specifier of the	remote kernel you wish to
	  monitor.  You	can also specify "*" to	monitor	ALL remote kernels.
	  If you do, your monitor will be called several times for a given
	  kernel.  This	is because a kernel has	one name and many aliases.
	  For example, a remote	kernel will have a unique ID within the	local
	  kernel, a name (passed to or generated by
	  create_ikc_{kernel,client}) and a globaly unique ID assigned by the
	  remote kernel	via $kernel->ID.  This suprises	some people, but see
	  the short note after the explanation of the callback parameters.

	  Note:	An effort has been made	to insure that when monitoring "*",
	  "register" is	first called with the remote kernel's unique ID, and
	  subsequent calls are aliases.	 This can't be guaranteed at this
	  time,	however.

       $states
	  Hashref that specifies what callback states are called when
	  something interesting	happens.  If $state is empty or	undef, the
	  session will no longer monitor the given remote kernel.

   Callback states
       The following states can	be monitored:

       "channel"
	     Called when a channel becomes ready or goes away.	ARG3 is	either
	     "ready" or	"close".  ARG4 is the numerical	ID of the channel's
	     session.  See "CHANNELS" below.

       "register"
	     Called when a remote kernel or alias is registered.  This is
	     equivalent	to when	the connection phase is	finished.

       "unregister"
	     Called when a remote kernel or alias is unregistered.  This is
	     equivalent	to when	the remote kernel disconnects.

       "subscribe"
	     Called when IKC succeeds in subscribing to	a remote session.
	     ARG3 is an	IKC::Specifier of what was subscribed to.  Use this
	     for posting to the	proxy session.

       "unsubscribe"
	     Called when IKC succeeds in unsubscribing from a remote session.

       "shutdown"
	     You are informed whenever someone tries to	do a sane shutdown of
	     IKC and all peripheral sessions.  This will called	only once,
	     after somebody posts an IKC/shutdown event.

       "error"
	     You are informed of errors	in local and remote kernels.  ARG3 is
	     the operation that	failed.	ARG4 is	the error message.  See
	     "ERRORS" below.

       "data"
	     Little bit	of data	(can be	scalar or reference) that is passed to
	     the callback.  This allows	you to more magic.

       The callback states are called the following parameters :

       "ARG0"
	     Name of the kernel	that was passed	to poe://*/IKC/monitor

       "ARG1"
	     ID	or alias of remote kernel from IKC's point of view.

       "ARG2"
	     A flag.  If this is true, then ARG1 is the	remote kernel unique
	     ID, if false, then	ARG1 is	an alias.  This	is mostly useful when
	     monitoring	"*" and	is in fact a bit bloatful.

       "ARG3"
	     "$state->{data}" ie any data you want.

       "ARG4" ... "ARGN"
	     Callback-specific parameters.  See	above.

       Most of the time, ARG0 and ARG1 will be the same.  Exceptions are if
       you are monitoring "*" or if you	supplied a full	IKC event specifier to
       IKC/monitor rather then just a plain kernel name.

   Short note about monitoring all kernels with	"*"
       There are 2 reasons circonstances in which you will be monitoring all
       remote kernels :	names known in advance and names unknown in advance.

       If you know kernel names	in advance, you	might be better	off monitoring
       a given kernel name.  However, you might	prefer doing a case-like
       compare on ARG1 (with regexes, say).  This would	be useful for
       clustering, where various redundant kernels could follow	a naming
       convention like [application]-[host], so	you could compare "ARG1" with
       "/^credit-/" to find out	if you want to set up specific things for that
       kernel.

       Not knowing the name of a kernel	in advance, you	could be doing some
       sort of autodiscovery or	maybe just monitoring for debuging, logging or
       book-keeping purposes.  You obviously don't want	to do autodiscovery
       for every alias of every	kernel,	only for the "cannonical name",	hence
       the need	for ARG2.

   Short note the second
       You are more then allowed (in fact, you are encouraged) to use the same
       callback	states when monitoring multiple	kernels.  In this case,	you
       will find ARG0 useful for telling them apart.

	   $kernel->post('IKC',	'monitor', '*',
			   {register=>'remote_register',
			    unregister=>'remote_unregister',
			    subscribe=>'remote_subscribe',
			    unsubscribe=>'remote_unsubscribe',
			    data=>'magic box'});

       Now remote_{register,unregister,subscribe,unsubscribe} is called	for
       any remote kernel.

	   $kernel->post('IKC',	'monitor', 'Pulse', {register=>'pulse_connected'});

       "pulse_connected" will be called	in current session when	you succeed in
       connecting to a kernel called 'Pulse'.

	   $kernel->post('IKC',	'monitor', '*');

       Session is no longer monitoring all kernels, only 'Pulse'.

	   $kernel->post('IKC',	'monitor', 'Pulse', {});

       Now we aren't even interested in	'Pulse';

CHANNELS
       Previous	versions of IKC	did not	adequately allow you to	control	a
       connection.  With 0.2400	we added a much	needed feature.

       Each connection to a remote kernel is handled by	a channel session.
       You find	out the	session's ID by	monitoring for "channel" operations.
       You may close a channel and the corresponding connection	to the remote
       kernel by sending it a "shutdown" event.

	   sub _start {
	       # set up	the monitor
	       $poe_kernel->call( IKC => monitor => '*'	=> { channel =>	'channel' } );
	   }

	   sub channel {
	       my( $self, $rid,	$rkernel, $real, $data,	$op, $channel )	= @_[ OBJECT, ARG0..$#_	];
	       return unless $real;    # only care about the real kernel ID
	       if( $op eq 'ready' ) {  # new channel is	ready
		   $self->{channel}{ $rkernel }	= $channel;
	       }
	       elsif( $op eq 'close' ) {   # channel is	gone
		   delete $self->{channel}{ $rkernel };
	       }
	   }

	   # this an event posted from your controler logic
	   sub close_channel {
	       my( $self, $rkernel ) = @_[ OBJECT, ARG0	];
	       # tell the channel to close
	       $poe_kernel->post( $self->{channel}{ $rkernel } => 'shutdown' );
	   }

ERRORS
       Previous	versions of IKC	did not	adequately allow you to	monitor	for
       errors on a connection.	With 0.2400 we started monitoring errors.

       There are 2 step	during which you can have errors: when opening the
       connection and during message exchange.	These 2	steps are handled
       diffrently.

       You use "on_error" in POE::Component::IKC::Client and "on_error"	in
       POE::Component::IKC::Server to receive errors while a connection	is
       being opened.  Note that	this includes the initial IKC handshake.

	   sub on_error
	   {
	       my( $op,	$errnum, $errstr ) = @_;
	       # Handle	this like you would any	POE socket error
	       # But remember you can't	rely on	your session being active
	   }

       You use "monitor" on error to receive errors during message exchange.
       ARG3 is the name	of the operation.  ARG4	is the error message.  Current
       operations are:

       remote-request
	   Remote kernel was unable to parse a request that was	sent from the
	   local kernel.

       remote-check
	   Remote kernel has not published an event that was sent from the
	   local kernel.

       remote-resolve
	   Remote kernel could not find	a session that could handle the
	   request.

       remote-invocation
	   Remote kernel had an	error when it tried to invoke the request
	   handler.  Please note this will not catch errors in the request
	   handler, but	only errors in the thunk.

       local-request
       local-check
       local-resolve
       local-invocation
	   These 4 operations are the local equivalent of the previous 4.
	   They	are intented for logging.  In general no actions are required.

	   Note	that 'local' and 'remote' refer	to where the operation
	   happened, not where the request originated.	As an example, kernel
	   A sends a poe://B/foo/bar request to	kernel B.  Kernel B has	not
	   published that event.  Monitors on kernel A will see	remote-check.
	   Monitors on kernel B	will see local-check.

       channel-error
	   Receive channel errors during message exchange.   Channel errors
	   are equivalent to POE wheel errors.	The message will be "[$errnum]
	   $errstr".

       subscribe
	   Failure to subscribe	to a remote session.

       fork
	   POE::Component::IKC::Server failed to fork.

       resolve
	   Error when trying to	find a remote kernel or	session.

       Example monitor for error events:

	   sub monitor_error
	   {
	       my( $self, $rid,	$kernel, $real,	$data, $op, $message ) =
		       @_[ OBJECT, ARG0	... $#_	];
	       if( $op =~ /^channel-/ and $message =~ /\[(\d+)\] (.*)/ ) {
		   return unless $real;
		   my( $errnum,	$errstr	) = ( $1, $2 );
		   if( $op eq 'channel-read' and $errnum == 0 )	{
		       warn "Connection	closed";
		       return;
		   }
	       }
	       warn "Error during $op: $message";
	   }

       In particular, you will note we don't do	anything when we detect	the
       channel closed.	Instead, it is recommended to attempt reconnection in
       the "unregister"	event.

EXPORTED FUNCTIONS
   "create_ikc_responder"
       DEPRECATED.  Please use

	   POE::Compontent::IKC::Responder->spawn();

PROXY SENDER
       Event handlers invoked via IKC will have	a proxy	SENDER session.	You
       may use it to post back to the remote session.

	   $poe_kernel->post( $_[SENDER], 'response', @args );

       Normally	this proxy session is available	during the invocation of the
       event handler.  You may claim it	for longer by setting an external
       reference:

	   $heap->{remote} = $_[SENDER]->ID;
	   $poe_kernel->refcount_increment( $heap->{remote}, 'MINE' );

       POE::Component::IKC will	detect this and	create a new proxy session for
       future calls.  It will then be UP TO YOU	to free	the session:

	   $poe_kernel->refcount_decrement( $heap->{remote}, 'MINE' );

       Note that you will have to publish any events that will be posted back.

BUGS
       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.

       The "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 about	the retraction.

       "call()"ing a state in a	proxied	foreign	session	doesn't	work, for
       obvious reasons.

AUTHOR
       Philip Gwyn, <perl-ikc at pied.nu>

COPYRIGHT AND LICENSE
       Copyright 1999-2014 by Philip Gwyn.  All	rights reserved.

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

       See <http://www.perl.com/language/misc/Artistic.html>

SEE ALSO
       POE, POE::Component::IKC::Server, POE::Component::IKC::Client,
       POE::Component::IKC::ClientLite,	POE::Component::IKC::Channel,
       POE::Component::IKC::Proxy, POE::Component::IKC::Freezer,
       POE::Component::IKC::Specifier.

perl v5.32.0			  2014-07-07		     IKC::Responder(3)

NAME | SYNOPSIS | DESCRIPTION | STATES/METHODS | CHANNELS | ERRORS | EXPORTED FUNCTIONS | PROXY SENDER | BUGS | AUTHOR | COPYRIGHT AND LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Component::IKC::Responder&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help