IKC::Server(3)

📦 version 0.2402, in arch rolling

💖 IKC::Server(3) — POE::Component::IKC::Server 💖

okay bestie, so this is the manual page for IKC::Server(3), which lives in the User Contributed Perl Documentation section, and honestly? it's a whole vibe. it's the POE Inter-kernel Communication server. let's get into it 🫶

✨ NAME ✨

POE::Component::IKC::Server — the POE Inter-kernel Communication server, aka the girl who answers the door when other kernels come knocking 💅

🎀 SYNOPSIS 🎀

use POE;
use POE::Component::IKC::Server;
POE::Component::IKC::Server->spawn(
    ip=>$ip,
    port=>$port,
    name=>'Server');
...
$poe_kernel->run();

that's it. that's the whole summoning ritual ✨

🦋 DESCRIPTION 🦋

so this module implements a POE IKC server, no cap. an IKC server just sits there listening for incoming connections from IKC clients — like, it's literally the social one at the party 🎉

when a client connects, it negociates certain connection parameters (yes, it's giving handshake diplomacy). and after that? bestie, the POE server and the client are pretty much identical. twins. matching outfits. iconic 👑

🌸 EXPORTED FUNCTIONS 🌸

create_ikc_server

Deprecated. 🚨 like, do not use this. use spawn in POE::Component::IKC::Server instead. moving on 💅

⭐ CLASS METHODS ⭐

spawn

this method initiates all the work of building the IKC server. it's the main character of this whole page, honestly. the parameters are:

  • ip — the address to listen on. can be a doted-quad ('127.0.0.1') or a host name ('foo.pied.nu'). defaults to '0.0.0.0', aka INADDR_ANY. she's flexible 💁‍♀️
  • port — the port to listen on. can be numeric (80) or a service ('http'). if it's undefined, it defaults to 603. and here's the fun part: if you set the port to 0, a random port gets chosen and spawn will return the port number 🎰
my $port = POE::Component::IKC::Server->spawn( port => 0 );
warn "Listeing on port $port";

(yes, "Listeing" — that's verbatim, i don't make the rules, i just report them 😭)

  • unix — path to the unix-socket to listen on. ⚠️ note: this path is unlinked before the socket is attempted! buyer beware, fr fr. it's giving "no take-backsies" 🙈
  • name — the local kernel name. this is how we shall "advertise" ourself to foreign kernels — it acts as a "kernel alias". 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 you can post to them as if they were remote. lowkey genius ✨
  • aliases — arrayref of even more aliases for this kernel. Fun Fun Fun! 🎉
  • verbose — if true, print extra information to STDERR. this lets you see what's going on and potentially trace down problems and stuff. your debug bestie 🔍
  • processes — activates the pre-forking server code. if set to a positive value, IKC will fork processes-1 children. IKC requests are only serviced by the children. the default is 1 (ie, no forking) 🧚
  • babysit — the time, in seconds, between invocations of the babysitter event. she's literally babysitting 👶
  • connections — the number of connections a child will accept before exiting. currently, connections are serviced concurrently, because there's no way to know when we have finished a request. defaults to 1 (ie, one connection per child).
  • concurrency — the number of simultaneous connected clients allowed. defaults to 0 (unlimited) 🌈
heads up: this is per-IKC::Server instance. if you have several ways of connecting to a give IKC server (for example, both an TCP/IP port and unix pipe), they will not share the conncurrent connection count. so like, they don't pool. okay? okay 💀
  • protocol — which IKC negociation protocol to use. the original protocol ("IKC") had a slow synchronous handshake. the new protocol ("IKC0") sends all the handshake information at once. IKC0 will degrade gracefully to IKC if the client and server don't match — she's adaptable like that 💅

default is IKC0.

  • on_error — a coderef that's called for all errors. you could use this to monitor for problems when forking children or opening the socket. the 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.

also note that the coderef will be executed from within an IKC session, NOT within your own session. this means things like $poe_kernel->delay_set() won't do what you think they should. surprise! 🙈

POE::Component::IKC::Server::spawn returns undef(), unless you specify a port=0, in which case spawn returns the port that was chosen. slay 🎀

🔥 EVENTS 🔥

shutdown

this event causes the server to close it's socket, clean up the shop and head home 🏠 normally it's only posted from IKC::Responder. like, it's an internal thing, iykyk.

💀 BUGS 💀

preforking is something of a hack. in particular, you must make sure that your sessions will permit children exiting — which means if you have a delay()-loop, or event loop, children will not exit 😭 once POE gets multicast events, this behaviour will change. so like, it's a known thing, don't come for her 💅

👑 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::Client

okay that's the whole page, bestie, you're officially an IKC server expert now, no cap 💜

perl v5.42.0 · 2025-12-14 · IKC::Server(3) — mwah, go forth and spawn servers ✨🎀🦋

📦 where this page comes from