.\" 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::ClientLite 3pm" .TH IKC::ClientLite 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::ClientLite \- Small client for IKC .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use POE::Component::IKC::ClientLite; \& \& $poe=create_ikc_client(port=>1337); \& die POE::Component::IKC::ClientLite::error() unless $poe; \& \& $poe\->post("Session/event", $param) \& or die $poe\->error; \& \& # bad way of getting a return value \& my $foo=$poe\->call("Session/other_event", $param) \& or die $poe\->error; \& \& # better way of getting a return value \& my $ret=$poe\->post_respond("Session/other_event", $param) \& or die $poe\->error; \& \& # make sure connectin is aliave \& $poe\->ping() \& or $poe\->disconnect; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" ClientLite is a small, pure-Perl \s-1IKC\s0 client implementation. It is very basic because it is intented to be used in places where \s-1POE\s0 wouldn't fit, like mod_perl. .PP It handles automatic reconnection. When you post an event, ClientLite will try to send the packet over the wire. If this fails, it tries to reconnect. If it can't it returns an error. If it can, it will send he packet again. If *this* fails, well, tough luck. .SH "METHODS" .IX Header "METHODS" .SS "create_ikc_client" .IX Subsection "create_ikc_client" Creates a new PoCo::IKC::ClientLite object. Parameters are supposedly compatible with PoCo::IKC::Client, but unix sockets aren't handled yet... What's more, there are 3 additional parameters: .IP "block_size" 4 .IX Item "block_size" Size, in octets (8 bit bytes), of each block that is read from the socket at a time. Defaults to \f(CW65535\fR. .IP "timeout" 4 .IX Item "timeout" Time, in seconds, that \f(CW\*(C`call\*(C'\fR and \f(CW\*(C`post_respond\*(C'\fR will wait for a response. Defaults to 30 seconds. .IP "connect_timeout" 4 .IX Item "connect_timeout" Time, in seconds, to wait for a phase of the connection negotiation to complete. Defaults to \f(CW\*(C`timeout\*(C'\fR. There are 4 phases of negotiation, so a the default \f(CW\*(C`connect_timeout\*(C'\fR of 30 seconds means it could potentialy take 2 minutes to connect. .IP "protocol" 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. .SS "connect" .IX Subsection "connect" .Vb 1 \& $poe\->connect or die $poe\->error; .Ve .PP Connects to the remote kernel if we aren't already. You can use this method to make sure that the connection is open before trying anything. .PP Returns true if connection was successful, false if not. You can check \&\*(L"error\*(R" to see what the problem was. .SS "disconnect" .IX Subsection "disconnect" Disconnects from remote \s-1IKC\s0 server. .SS "error" .IX Subsection "error" .Vb 2 \& my $error=POE::Component::IKC::ClientLite::error(); \& $error=$poe\->error(); .Ve .PP Returns last error. Can be called as a object method, or as a global function. .SS "post" .IX Subsection "post" .Vb 1 \& $poe\->post($specifier, $data); .Ve .PP Posts the event specified by \f(CW$specifier\fR to the remote kernel. \f(CW$data\fR is any parameters you want to send along with the event. It will return 1 on success (ie, data could be sent... not that the event was received) and \&\fIundef()\fR if we couldn't connect or reconnect to remote kernel. .SS "post_respond" .IX Subsection "post_respond" .Vb 1 \& my $ret=$poe\->post_respond($specifier, $data); .Ve .PP Posts the event specified by \f(CW$specifier\fR to the remote kernel. \f(CW$data\fR is any parameters you want to send along with the event. It waits until the remote kernel sends a message back and returns it's payload. Waiting timesout after whatever you value you gave to POE::Component::IKC::Client\->spawn. .PP Events on the far side have to be aware of post_respond. In particular, \&\s-1ARG0\s0 is not \f(CW$data\fR as you would expect, but an arrayref that contains \&\f(CW$data\fR followed by a specifier that should be used to post back. .PP .Vb 7 \& sub my_event \& { \& my($kernel, $heap, $args)=@_[KERNEL, HEAP, ARG0]; \& my $p=$args\->[0]; \& $heap\->{rsvp}=$args\->[1]; \& # .... do lotsa stuff here \& } \& \& # eventually, we are finished \& sub finished \& { \& my($kernel, $heap, $return)=@_[KERNEL, HEAP, ARG0]; \& $kernel\->post(IKC=>\*(Aqpost\*(Aq, $heap\->{rsvp}, $return); \& } .Ve .SS "responded" .IX Subsection "responded" .Vb 2 \& my $ret = $poe\->responded( $state ); \& my @ret = $poe\->responded( $state ); .Ve .PP Waits for \f(CW$state\fR from the remote kernel. \f(CW$state\fR must be a simple state name. Any requests from the remotre kernel for other states are rejected. A remote handler would respond by using the proxy sender. .SS "call" .IX Subsection "call" .Vb 1 \& my $ret=$poe\->call($specifier, $data); .Ve .PP This is the bad way to get information back from the a remote event. Follows the expected semantics from standard \s-1POE\s0. It works better then post_respond, however, because it doesn't require you to change your interface or write a wrapper. .SS "ping" .IX Subsection "ping" .Vb 3 \& unless($poe\->ping) { \& # connection is down! connection is down! \& } .Ve .PP Find out if we are still connected to the remote kernel. This method will \&\s-1NOT\s0 try to reconnect to the remote server .SS "name" .IX Subsection "name" Returns our local name. This is what the remote kernel thinks we are called. I can't really say this is the local kernel name, because, well, this isn't really a kernel. But hey. .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