NAME

       POE::Component::IKC::Channel - POE Inter-Kernel Communication I/O session

SYNOPSIS

           use POE;
           use POE::Component::IKC::Channel;

           POE::Component::IKC::Channel->spawn( %params );

DESCRIPTION

       You will never use an IKC Channel directly.  They are created by
       POE::Component::IKC::Server and POE::Component::IKC::Client as needed.

       This module implements an POE IKC I/O.  When a new connection is established,
       "IKC::Server" and "IKC::Client" create an "IKC::Channel" to handle the I/O.

       IKC communication happens in 2 phases : negociation phase and normal phase.

       The negociation phase uses "Filter::Line" and is used to exchange various parameters
       between kernels (example : kernel names, what type of freeze/thaw to use, etc).  After
       negociation, "IKC::Channel" switches to a "Filter::Reference" and creates a
       "IKC::Responder", if needed.  After this, the channel forwards reads and writes between
       "Wheel::ReadWrite" and the Responder.

       "IKC::Channel" is also in charge of cleaning up kernel names when the foreign kernel
       disconnects.

METHODS

   spawn
           POE::Component::IKC::Channel->spawn(%param);

       Creates a new IKC channel to handle the negociations then the actual data.

       Parameters are keyed as follows:

       handle
           The perl handle we should hand to "Wheel::ReadWrite::new".

       kernel_name
           The name of the local kernel.  This is a stop-gap until event naming has been
           resolved.

       on_connect
           Code ref that is called when the negociation phase has terminated.  Normaly, you would
           use this to start the sessions that post events to foreign kernels.

       subscribe
           Array ref of specifiers (either foreign sessions, or foreign states) that you want to
           subscribe to.  $on_connect will only be called if you can subscribe to all those
           specifiers.  If it can't, it will die().

       unix
           A flag indicating that the handle is a Unix domain socket or not.

       aliases
           Arrayref of aliases for the local kernel.

       serializers
           Arrayref or scalar of the packages that you want to use for data serialization.  A
           serializer package requires 2 functions : freeze (or nfreeze) and thaw.  See
           "POE::Component::IKC::Client".

       "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 currently IKC but will move to IKC0 when I'm confident in the new protocol.

EVENTS

   shutdown
       This event causes the server to close it's socket and skiddadle on down the road.
       Normally it is only posted from IKC::Responder.

       If you want to post this event yourself, you can get the channel's session ID from
       IKC::Client's on_connect:

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

       Then, when it becomes time to disconnect:

           $poe_kernel->call($heap->{channel} => 'shutdown');

       Yes, this is a hack.  A cleaner machanism needs to be provided.

EXPORTED FUNCTIONS

   create_ikc_channel
       Deprecated.

BUGS

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::Responder