NAME

       POE::Component::IKC::Client - POE Inter-Kernel Communication client

SYNOPSIS

           use POE;
           use POE::Component::IKC::Client;
           POE::Component::IKC::Client->spawn(
               ip=>$ip,
               port=>$port,
               name=>"Client$$",
               subscribe=>[qw(poe:/*/timserver)]
           );
           ...
           $poe_kernel->run();

DESCRIPTION

       This module implements an POE IKC client.  An IKC client attempts to connect to a IKC
       server.  If successful, it negociates certain connection parameters.  After this, the POE
       server and client are pretty much identical.

EXPORTED FUNCTIONS

   create_ikc_client
       Syntatic sugar for POE::Component::IKC::Client->spawn.

CLASS METHODS

   spawn
       This methods initiates all the work of connecting to an IKC server.  Parameters are :

       "ip"
           Address to connect to.  Can be a doted-quad ('127.0.0.1') or a host name
           ('foo.pied.nu').  Defaults to '127.0.0.1', aka INADDR_LOOPBACK.

       "port"
           Port to connect to.  Can be numeric (80) or a service ('http').

       "unix"
           Path to unix-domain socket that the server is listening on.

       "name"
           Local kernel name.  This is how we shall "advertise" ourself to foreign kernels. It
           acts as a "kernel alias".  This parameter is temporary, pending the addition of true
           kernel names in the POE core.  This name, and all aliases will be registered with the
           responder so that you can post to them as if they were remote.

       "aliases"
           Arrayref of even more aliases for this kernel.  Fun Fun Fun!

       "on_connect"
           Coderef that is called when the connection has been made to the foreign kernel.
           Normaly, you would use this to start the sessions that post events to foreign kernels.

           Note, also, that the coderef will be executed from within an IKC channel session, NOT
           within your own session.  This means that things like $poe_kernel->delay_set() won't
           do what you think they should.

           It does, however, mean that you can get the session ID of the IKC channel for this
           connection.

               POE::Component::IKC::Client->spawn(
                   ....
                       on_connect=>sub {
                           $heap->{channel} = $poe_kernel->get_active_session()->ID;
                       },
                   ....
                   );

           However, IKC/monitor provides a more powerful mechanism for detecting connections.
           See POE::Component::IKC::Responder.

       "on_error"
           Coderef that is called for all connection errors. You could use this to restart the
           connection attempt.  Parameters are "$operation, $errnum and $errstr", which
           correspond to POE::Wheel::SocketFactory's FailureEvent, which q.v.

           However, IKC/monitor provides a more powerful mechanism for detecting errors.  See
           POE::Component::IKC::Responder.

           Note, also, that the coderef will be executed from within an IKC session, NOT within
           your own session.  This means that things like $poe_kernel->delay_set() won't do what
           you think they should.

       "subscribe"
           Array ref of specifiers (either foreign sessions, or foreign states) that you want to
           subscribe to.  on_connect will only be called when IKC has managed to subscribe to all
           specifiers.  If it can't, it will die().  YOW that sucks.  "monitor" will save us all.

       "serializers"
           Arrayref or scalar of the packages that you want to use for data serialization.  First
           IKC tries to load each package.  Then, when connecting to a server, it asks the server
           about each one until the server agrees to a serializer that works on its side.

           A serializer package requires 2 functions : freeze (or nfreeze) and thaw.  See
           "POE::Filter::Reference".

           The default is "[qw(Storable FreezeThaw POE::Component::IKC::Freezer)]".  "Storable"
           and "FreezeThaw" are modules in C on CPAN.  They are much much much faster then IKC's
           built-in serializer "POE::Component::IKC::Freezer".  This serializer uses
           "Data::Dumper" and "eval $code" to get the deed done.  There is an obvious security
           problem here.  However, it has the advantage of being pure Perl and all modules come
           with the core Perl distribution.

           It should be noted that you should have the same version of "Storable" on both sides,
           because some versions aren't mutually compatible.

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

BUGS

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::Server, POE::Component::IKC::Responder.