.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "IKC::Channel 3pm" .TH IKC::Channel 3pm "2011-08-27" "perl v5.12.4" "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 4 \& use POE; \& use POE::Component::IKC::Channel; \& create_ikc_channel($handle, $name, $on_connect, $subscribe, \& $rname, $unix); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements an \s-1POE\s0 \s-1IKC\s0 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 \&\s-1IKC\s0 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 "EXPORTED FUNCTIONS" .IX Header "EXPORTED FUNCTIONS" .SS "create_ikc_channel" .IX Subsection "create_ikc_channel" This function initiates all the work of connecting to a \s-1IKC\s0 connection channel. It is a wrapper around \f(CW\*(C`spawn\*(C'\fR. .SH "METHODS" .IX Header "METHODS" .SS "spawn" .IX Subsection "spawn" .Vb 1 \& POE::Component::IKC::Channel\->spawn(%param); .Ve .PP Creates a new \s-1IKC\s0 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 \fIdie()\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 \s-1IKC\s0 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. \s-1IKC0\s0 will degrade gracefully to \s-1IKC\s0, if the client and server don't match. .Sp Default currently \s-1IKC\s0 but will move to \s-1IKC0\s0 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 \s-1ID\s0 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 "BUGS" .IX Header "BUGS" .SH "AUTHOR" .IX Header "AUTHOR" Philip Gwyn, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 1999\-2011 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 .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1POE\s0, POE::Component::IKC::Server, POE::Component::IKC::Client, POE::Component::IKC::Responder