IKC::Client(3)

📦 version 0.2402, in arch rolling

🦋 IKC::Client(3) — like, the POE Inter-Kernel Communication client bestie 💅

okay so this is POE::Component::IKC::Client, from the User Contributed Perl Documentation, and it's genuinely one of those pages you're gonna wanna read twice because there's lore here. stay with me 🫶

✨ NAME ✨

POE::Component::IKC::Client — the POE Inter-Kernel Communication client. that's it, that's the name, she's iconic 👑

🌸 SYNOPSIS 🌸

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();

like yes, that's the whole vibe. ... in the middle means "your code goes here, bestie, i can't do everything for you" 😭

💖 DESCRIPTION 💖

So. This module implements a POE IKC client. An IKC client attempts to connect to an IKC server — note the word "attempts", she's trying her best 🥺. If it's successful, it negociates certain connection parameters (yes, that's how it's spelled in the original, no i will not be fixing it, she's got character). After all that, the POE server and client are pretty much identical. twin energy. fr fr 🫶

🎀 EXPORTED FUNCTIONS 🎀

⭐ create_ikc_client

Syntactic sugar for POE::Component::IKC::Client->spawn. that's it. that's the whole function. she's a little shortcut and we love her 💅

🔥 CLASS METHODS 🔥

👑 spawn

This method initiates all the work of connecting to an IKC server. like, the whole thing. the main character method. Parameters are:

  • ip — the address to connect to. Can be a dotted-quad ('127.0.0.1') or a host name ('foo.pied.nu'). Defaults to '127.0.0.1', aka INADDR_LOOPBACK. (the original says "doted-quad", which is adorable, but you know what it means 🍓)
  • port — the port to connect to. Can be numeric (80) or a service ('http').
  • unix — path to the unix-domain socket that the server is listening on.
  • name — the local kernel name. This is how we "advertise" ourself to foreign kernels. It acts as a "kernel alias". Heads up: this parameter is temporary, pending the addition of true kernel names in the POE core. This name, and all aliases, will be registered with the responder so that you can post to them as if they were remote. sneaky but legal 😌
  • aliases — arrayref of even more aliases for this kernel. Fun Fun Fun! 🎉
  • on_connect — coderef that gets called when the connection has been made to the foreign kernel. Normally you'd use this to start the sessions that post events to foreign kernels.
⚠️ note, also, that the coderef will be executed from within an IKC channel session, NOT within your own session. This means that things like $poe_kernel->delay_set() won't do what you think they should. like, read that twice. it's giving "it's not you, it's the session" 💀

It does, however, mean you can get the session ID of the IKC channel for this connection:

POE::Component::IKC::Client->spawn(
    ....
        on_connect=>sub {
            $heap->{channel} = $poe_kernel->get_active_session()->ID;
        },
    ....
    );

However, IKC/monitor provides a more powerful mechanism for detecting connections. See POE::Component::IKC::Responder. ✨

  • on_error — coderef that's called for all connection errors. You could use this to restart the connection attempt. Parameters are $operation, $errnum and $errstr, which correspond to POE::Wheel::SocketFactory's FailureEvent, which q.v.

However, IKC/monitor provides a more powerful mechanism for detecting errors. See POE::Component::IKC::Responder.

⚠️ note, also, that the coderef will be executed from within an IKC session, NOT within your own session. So again: $poe_kernel->delay_set() won't do what you think it should. same trap, different door 🙈
  • subscribe — array ref of specifiers (either foreign sessions, or foreign states) that you want to subscribe to. on_connect will only be called when IKC has managed to subscribe to all specifiers. If it can't, it will die(). YOW that sucks. "monitor" will save us all. 😭
  • serializers — arrayref or scalar of the packages you want to use for data serialization. First IKC 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.

A serializer package requires 2 functions: freeze (or nfreeze) and thaw. See "POE::Filter::Reference".

The default is [qw(Storable FreezeThaw POE::Component::IKC::Freezer)]. Storable and FreezeThaw are modules in C on CPAN. They are much much much faster then IKC's built-in serializer POE::Component::IKC::Freezer. This serializer uses Data::Dumper and eval $code 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.

💀 It should be noted that you should have the same version of Storable on both sides, because some versions aren't mutually compatible. no cap, that'll ruin your whole day.
  • 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. she's flexible, she's adaptable, she's slay 🌈

Default is IKC0.

💀 BUGS 💀

...nothing listed here. the BUGS section is literally empty. not me staring at an empty section 😭 (that's genuinely what's in the original — no bugs listed, so no bugs invented. we don't make things up in this house 🙅)

🧚 AUTHOR 🧚

Philip Gwyn, <perl-ikc at pied.nu> — the icon who made all this happen 👑

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::Server
  • POE::Component::IKC::Responder

okay that's the whole page, bestie, go build something cute 🫶

~ cute sign-off ~ this was perl v5.42.0, dated 2025-12-14, page IKC::Client(3). mwah 💋✨

📦 where this page comes from