.\" 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::Client 3pm"
.TH IKC::Client 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::Client \- POE Inter\-Kernel Communication client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements an \s-1POE\s0 \s-1IKC\s0 client.  An \s-1IKC\s0 client attempts to connect
to a \s-1IKC\s0 server.  If successful, it negociates certain connection
parameters.  After this, the \s-1POE\s0 server and client are pretty much
identical.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.SS "create_ikc_client"
.IX Subsection "create_ikc_client"
Syntatic sugar for POE::Component::IKC::Client\->spawn.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS "spawn"
.IX Subsection "spawn"
This methods initiates all the work of connecting to an \s-1IKC\s0 server.
Parameters are :
.ie n .IP """ip""" 4
.el .IP "\f(CWip\fR" 4
.IX Item "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 \s-1INADDR_LOOPBACK\s0.
.ie n .IP """port""" 4
.el .IP "\f(CWport\fR" 4
.IX Item "port"
Port to connect to.  Can be numeric (80) or a service ('http').
.ie n .IP """unix""" 4
.el .IP "\f(CWunix\fR" 4
.IX Item "unix"
Path to unix-domain socket that the server is listening on.
.ie n .IP """name""" 4
.el .IP "\f(CWname\fR" 4
.IX Item "name"
Local kernel name.  This is how we shall \*(L"advertise\*(R" ourself to foreign
kernels. It acts as a \*(L"kernel alias\*(R".  This parameter is temporary, pending
the addition of true kernel names in the \s-1POE\s0 core.  This name, and all
aliases will be registered with the responder so that you can post to them
as if they were remote.
.ie n .IP """aliases""" 4
.el .IP "\f(CWaliases\fR" 4
.IX Item "aliases"
Arrayref of even more aliases for this kernel.  Fun Fun Fun!
.ie n .IP """on_connect""" 4
.el .IP "\f(CWon_connect\fR" 4
.IX Item "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.
.Sp
Note, also, that the coderef will be executed from within an \s-1IKC\s0 channel
session, \s-1NOT\s0 within your own session.  This means that things like
\&\f(CW$poe_kernel\fR\->\fIdelay_set()\fR won't do what you think they should.
.Sp
It does, however, mean that you can get the session \s-1ID\s0 of the \s-1IKC\s0 channel for
this connection.
.Sp
.Vb 7
\&    POE::Component::IKC::Client\->spawn(
\&        ....
\&            on_connect=>sub {
\&                $heap\->{channel} = $poe_kernel\->get_active_session()\->ID;
\&            },
\&        ....
\&        );
.Ve
.Sp
However, IKC/monitor provides a more powerful mechanism for detecting
connections.  See POE::Component::IKC::Responder.
.ie n .IP """on_error""" 4
.el .IP "\f(CWon_error\fR" 4
.IX Item "on_error"
Coderef that is called for all connection errors. You could use this to
restart the connection attempt.  Parameters are \f(CW\*(C`$operation, $errnum and
$errstr\*(C'\fR, which correspond to POE::Wheel::SocketFactory's FailureEvent, 
which q.v.
.Sp
However, IKC/monitor provides a more powerful mechanism for detecting
errors.  See POE::Component::IKC::Responder.
.Sp
Note, also, that the coderef will be executed from within an \s-1IKC\s0 session,
\&\s-1NOT\s0 within your own session.  This means that things like
\&\f(CW$poe_kernel\fR\->\fIdelay_set()\fR won't do what you think they should.
.ie n .IP """subscribe""" 4
.el .IP "\f(CWsubscribe\fR" 4
.IX Item "subscribe"
Array ref of specifiers (either foreign sessions, or foreign states) that
you want to subscribe to.  on_connect will only be called when \s-1IKC\s0 has
managed to subscribe to all specifiers.  If it can't, it will \fIdie()\fR.  \s-1YOW\s0
that sucks.  \f(CW\*(C`monitor\*(C'\fR will save us all.
.ie n .IP """serializers""" 4
.el .IP "\f(CWserializers\fR" 4
.IX Item "serializers"
Arrayref or scalar of the packages that you want to use for data
serialization.  First \s-1IKC\s0 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.
.Sp
A serializer package requires 2 functions : freeze (or nfreeze) and thaw. 
See \f(CW\*(C`POE::Filter::Reference\*(C'\fR.
.Sp
The default is \f(CW\*(C`[qw(Storable FreezeThaw
POE::Component::IKC::Freezer)]\*(C'\fR.  \f(CW\*(C`Storable\*(C'\fR and \f(CW\*(C`FreezeThaw\*(C'\fR are
modules in C on \s-1CPAN\s0.  They are much much much faster then \s-1IKC\s0's built-in
serializer \f(CW\*(C`POE::Component::IKC::Freezer\*(C'\fR.  This serializer uses
\&\f(CW\*(C`Data::Dumper\*(C'\fR and \f(CW\*(C`eval $code\*(C'\fR 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.
.Sp
It should be noted that you should have the same version of \f(CW\*(C`Storable\*(C'\fR on
both sides, because some versions aren't mutually compatible.
.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 is \s-1IKC0\s0.
.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\-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 <http://www.perl.com/language/misc/Artistic.html>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1POE\s0, POE::Component::IKC::Server, POE::Component::IKC::Responder.