IKC::ClientLite(3)

📦 version 0.2402, in arch rolling

💖 IKC::ClientLite(3) 💖

okay so this is a page from the User Contributed Perl Documentation manual, and honestly? it's a little bop. it's POE::Component::IKC::ClientLite, bestie, and it's here to make IKC work in places where full POE simply cannot go. let's get into it. 🫶

✨ NAME ✨

POE::Component::IKC::ClientLite — a small client for IKC. tiny. compact. iconic. 💅

🌸 SYNOPSIS 🌸

use POE::Component::IKC::ClientLite;

$poe = POE::Component::IKC::ClientLite->new(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;
yeah the comments in there are a whole mood, but they are exactly as written, kay? iykyk. 💀

🦋 DESCRIPTION 🦋

ClientLite is a small, pure-Perl IKC client implementation. it's super basic on purpose, because it's intented to be used in places where POE wouldn't fit, like mod_perl. no cap.

it handles automatic reconnection, which is lowkey its whole thing. when you post an event, ClientLite tries to send the packet over the wire. if that fails, it tries to reconnect. if it can't, it returns an error. if it can, it sends he packet again. and if that fails? well. tough luck. 😭

🎀 METHODS 🎀

⭐ spawn

my $poe = POE::Component::IKC::ClientLite->spawn( %params );

creates a brand new PoCo::IKC::ClientLite object. the parameters are supposedly compatible with PoCo::IKC::Client, but heads up: unix sockets aren't handled yet... 🙈 what's more, there are 3 additional parameters:

🌈 block_size

size, in octets (8 bit bytes 💅), of each block that is read from the socket at a time. defaults to 65535.

🌈 timeout

time, in seconds, that call and post_respond will wait for a response. defaults to 30 seconds.

🌈 connect_timeout

time, in seconds, to wait for a phase of the connection negotiation to complete. defaults to timeout. and listen — there are 4 phases of negotiation, so a default connect_timeout of 30 seconds means it could potentialy take 2 minutes to connect. plan accordingly, bestie. ⏳

🌈 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. matching is important, okay??

default is IKC0. 👑

⭐ connect

$poe->connect or die $poe->error;

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. honestly a great little pre-game ritual. ✨

returns true if connection was successful, false if not. you can check error to see what the problem was.

⭐ disconnect

disconnects from remote IKC server. bye bestie 👋

⭐ error

my $error=POE::Component::IKC::ClientLite::error();
$error=$poe->error();

returns last error. can be called as a object method, or as a global function. both slay, pick your vibe. 💜

⭐ post

$poe->post($specifier, $data);

posts the event specified by $specifier to the remote kernel. $data 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 undef() if we couldn't connect or reconnect to remote kernel.

⭐ post_respond

my $ret=$poe->post_respond($specifier, $data);

posts the event specified by $specifier to the remote kernel. $data 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.

⚠️ okay this next bit is the important bit — events on the far side have to be aware of post_respond. in particular, ARG0 is not $data as you would expect, but an arrayref that contains $data followed by a specifier that should be used to post back. not me warning you twice. 🫶
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=>'post', $heap->{rsvp}, $return);
}

⭐ responded

my $ret = $poe->responded( $state );
my @ret = $poe->responded( $state );

waits for $state from the remote kernel. $state 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.

⭐ call

my $ret=$poe->call($specifier, $data);

this is the bad way to get information back from the a remote event. it follows the expected semantics from standard POE. it works better then post_respond, however, because it doesn't require you to change your interface or write a wrapper. so like... bad way but also kind of the convenient way? make it make sense. 😭

⭐ ping

unless($poe->ping) {
    # connection is down!  connection is down!
}

find out if we are still connected to the remote kernel. 🩺

⚠️ this method will NOT try to reconnect to the remote server. it's a vibe check, not a rescue mission.

⭐ 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. 🤷‍♀️

💫 FUNCTIONS 💫

🧚 create_ikc_client

DEPRECATED. use "spawn" in POE::Compoent::IKC::ClientLite instead. (yes that spelling is what it says, don't come for me 💀)

👑 AUTHOR 👑

Philip Gwyn, <perl-ikc at pied.nu>

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

aaand that's the whole page, bestie! ✨ this was IKC::ClientLite(3), part of perl v5.42.0, dated 2025-12-14 — go forth and connect responsibly. 💖🎀🦋

📦 where this page comes from