.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IKC::Channel 3"
.TH IKC::Channel 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
POE::Component::IKC::Channel \- POE Inter\-Kernel Communication I/O session
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    use POE;
\&    use POE::Component::IKC::Channel;
\&
\&    POE::Component::IKC::Channel\->spawn( %params );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
You will never use an IKC Channel directly.  They are created by
POE::Component::IKC::Server and POE::Component::IKC::Client as needed.
.PP
This module implements an POE IKC I/O.  When a new connection is
established, \f(CW\*(C`IKC::Server\*(C'\fR and \f(CW\*(C`IKC::Client\*(C'\fR create an \f(CW\*(C`IKC::Channel\*(C'\fR to
handle the I/O.
.PP
IKC communication happens in 2 phases : negociation phase and normal phase.
.PP
The negociation phase uses \f(CW\*(C`Filter::Line\*(C'\fR and is used to exchange various
parameters between kernels (example : kernel names, what type of freeze/thaw
to use, etc).  After negociation, \f(CW\*(C`IKC::Channel\*(C'\fR switches to a
\&\f(CW\*(C`Filter::Reference\*(C'\fR and creates a \f(CW\*(C`IKC::Responder\*(C'\fR, if needed.  After
this, the channel forwards reads and writes between \f(CW\*(C`Wheel::ReadWrite\*(C'\fR and
the Responder.
.PP
\&\f(CW\*(C`IKC::Channel\*(C'\fR is also in charge of cleaning up kernel names when
the foreign kernel disconnects.
.SH METHODS
.IX Header "METHODS"
.SS spawn
.IX Subsection "spawn"
.Vb 1
\&    POE::Component::IKC::Channel\->spawn(%param);
.Ve
.PP
Creates a new IKC channel to handle the negociations then the actual data.
.PP
Parameters are keyed as follows:
.IP handle 4
.IX Item "handle"
The perl handle we should hand to \f(CW\*(C`Wheel::ReadWrite::new\*(C'\fR.
.IP kernel_name 4
.IX Item "kernel_name"
The name of the local kernel.  \fBThis is a stop-gap until event naming
has been resolved\fR.
.IP on_connect 4
.IX Item "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.
.IP subscribe 4
.IX Item "subscribe"
Array ref of specifiers (either foreign sessions, or foreign states) that
you want to subscribe to.  \f(CW$on_connect\fR will only be called if you can
subscribe to all those specifiers.  If it can't, it will \fBdie()\fR.
.IP unix 4
.IX Item "unix"
A flag indicating that the handle is a Unix domain socket or not.
.IP aliases 4
.IX Item "aliases"
Arrayref of aliases for the local kernel.
.IP serializers 4
.IX Item "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 \f(CW\*(C`POE::Component::IKC::Client\*(C'\fR.
.ie n .IP """protocol""" 4
.el .IP \f(CWprotocol\fR 4
.IX Item "protocol"
Which IKC negociation protocol to use.  The original protocol (\f(CW\*(C`IKC\*(C'\fR) was
synchronous and slow.  The new protocol (\f(CW\*(C`IKC0\*(C'\fR) sends all information at
once.  IKC0 will degrade gracefully to IKC, if the client and server don't
match.
.Sp
Default currently IKC but will move to IKC0 when I'm confident in the new
protocol.
.SH EVENTS
.IX Header "EVENTS"
.SS shutdown
.IX Subsection "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.
.PP
If you want to post this event yourself, you can get the channel's
session ID from IKC::Client's on_connect:
.PP
.Vb 7
\&    POE::Component::IKC::Client\->spawn(
\&        ....
\&            on_connect=>sub {
\&                $heap\->{channel} = $poe_kernel\->get_active_session()\->ID;
\&            },
\&        ....
\&        );
.Ve
.PP
Then, when it becomes time to disconnect:
.PP
.Vb 1
\&    $poe_kernel\->call($heap\->{channel} => \*(Aqshutdown\*(Aq);
.Ve
.PP
Yes, this is a hack.  A cleaner machanism needs to be provided.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.SS create_ikc_channel
.IX Subsection "create_ikc_channel"
Deprecated.
.SH BUGS
.IX Header "BUGS"
.SH AUTHOR
.IX Header "AUTHOR"
Philip Gwyn, <perl\-ikc at pied.nu>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 1999\-2014 by Philip Gwyn.  All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.PP
See <http://www.perl.com/language/misc/Artistic.html>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
POE, POE::Component::IKC::Server, POE::Component::IKC::Client,
POE::Component::IKC::Responder