IKC::ClientLite(3pm)					User Contributed Perl Documentation				      IKC::ClientLite(3pm)

NAME

       POE::Component::IKC::ClientLite - Small client for IKC

SYNOPSIS

	   use POE::Component::IKC::ClientLite;

	   $poe=create_ikc_client(port=>1337);
	   die POE::Component::IKC::ClientLite::error() unless $poe;

	   $poe->post("Session/event", $param)
	       or die $poe->error;

	   # bad way of getting a return value
	   my $foo=$poe->call("Session/other_event", $param)
	       or die $poe->error;

	   # better way of getting a return value
	   my $ret=$poe->post_respond("Session/other_event", $param)
	       or die $poe->error;

	   # make sure connectin is aliave
	   $poe->ping()
	       or $poe->disconnect;

DESCRIPTION

       ClientLite is a small, pure-Perl IKC client implementation.  It is very basic because it is intented to be used in places where POE
       wouldn't fit, like mod_perl.

       It handles automatic reconnection.  When you post an event, ClientLite will try to send the packet over the wire.  If this fails, it tries
       to reconnect.  If it can't it returns an error.	If it can, it will send he packet again.  If *this* fails, well, tough luck.

METHODS

   create_ikc_client
       Creates a new PoCo::IKC::ClientLite object.  Parameters are supposedly compatible with PoCo::IKC::Client, but unix sockets aren't handled
       yet...  What's more, there are 3 additional parameters:

       block_size
	   Size, in octets (8 bit bytes), of each block that is read from the socket at a time.  Defaults to 65535.

       timeout
	   Time, in seconds, that "call" and "post_respond" will wait for a response.  Defaults to 30 seconds.

       connect_timeout
	   Time, in seconds, to wait for a phase of the connection negotiation to complete.  Defaults to "timeout".  There are 4 phases of
	   negotiation, so a the default "connect_timeout" of 30 seconds means it could potentialy take 2 minutes to connect.

       protocol
	   Which IKC negociation protocol to use.  The original protocol ("IKC") was synchronous and slow.  The new protocol ("IKC0") sends all
	   information at once.  IKC0 will degrade gracefully to IKC, if the client and server don't match.

	   Default is IKC0.

   connect
	   $poe->connect or die $poe->error;

       Connects to the remote kernel if we aren't already. You can use this method to make sure that the connection is open before trying
       anything.

       Returns true if connection was successful, false if not.  You can check "error" to see what the problem was.

   disconnect
       Disconnects from remote IKC server.

   error
	   my $error=POE::Component::IKC::ClientLite::error();
	   $error=$poe->error();

       Returns last error.  Can be called as a object method, or as a global function.

   post
	   $poe->post($specifier, $data);

       Posts the event specified by $specifier to the remote kernel.  $data is any parameters you want to send along with the event.  It will
       return 1 on success (ie, data could be sent... not that the event was received) and undef() if we couldn't connect or reconnect to remote
       kernel.

   post_respond
	   my $ret=$poe->post_respond($specifier, $data);

       Posts the event specified by $specifier to the remote kernel.  $data is any parameters you want to send along with the event.  It waits
       until the remote kernel sends a message back and returns it's payload.  Waiting timesout after whatever you value you gave to
       POE::Component::IKC::Client->spawn.

       Events on the far side have to be aware of post_respond.  In particular, ARG0 is not $data as you would expect, but an arrayref that
       contains $data followed by a specifier that should be used to post back.

	   sub my_event
	   {
	       my($kernel, $heap, $args)=@_[KERNEL, HEAP, ARG0];
	       my $p=$args->[0];
	       $heap->{rsvp}=$args->[1];
	       # .... do lotsa stuff here
	   }

	   # eventually, we are finished
	   sub finished
	   {
	       my($kernel, $heap, $return)=@_[KERNEL, HEAP, ARG0];
	       $kernel->post(IKC=>'post', $heap->{rsvp}, $return);
	   }

   responded
	   my $ret = $poe->responded( $state );
	   my @ret = $poe->responded( $state );

       Waits for $state from the remote kernel.  $state must be a simple state name.  Any requests from the remotre kernel for other states are
       rejected.  A remote handler would respond by using the proxy sender.

   call
	   my $ret=$poe->call($specifier, $data);

       This is the bad way to get information back from the a remote event.  Follows the expected semantics from standard POE.	It works better
       then post_respond, however, because it doesn't require you to change your interface or write a wrapper.

   ping
	   unless($poe->ping) {
	       # connection is down!  connection is down!
	   }

       Find out if we are still connected to the remote kernel.  This method will NOT try to reconnect to the remote server

   name
       Returns our local name.	This is what the remote kernel thinks we are called.  I can't really say this is the local kernel name, because,
       well, this isn't really a kernel.  But hey.

AUTHOR

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

COPYRIGHT AND LICENSE

       Copyright 1999-2011 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

perl v5.12.4							    2011-08-27						      IKC::ClientLite(3pm)