Child(3)

📦
version 1.39 · 2 versions
, in fedora 43

💖 Child(3) — POE::Component::Child 💖

okay bestie, sit down, we're talking about POE::Component::Child from the perl manual, page Child(3) — a whole little component that handles your child processes for you. it's giving babysitter but for fork. 🍼✨

🌸 NAME 🌸

POE::Component::Child — the child management component. yes literally, it manages children. no cap. 👑

✨ SYNOPSIS ✨

use POE qw(Component::Child);

$p = POE::Component::Child->new();
$p->run("ls", "-alF", "/tmp");

POE::Kernel->run();

that's it. that's the whole vibe. you make one, you tell it what to run, you let the kernel cook. 🔥

🦋 DESCRIPTION 🦋

so like… this POE component is basically a glow-up wrapper around POE::Wheel::Run. the whole point of it is that you do not have to go make a whole entire session just to catch the events it's throwing at you. it obviates that need. obviates!! 💅

🎀 METHODS 🎀

the module serves up an object-oriented interface, and here's the tea on every single method:

🌈 new [hash[-ref]]

used to initialise the system and create a component instance. you can hand it either a hash or a reference to a hash. the keys listed below mean something to the component — everything else just gets passed along to the callbacks you provided.

  • alias — names the session that module callbacks get posted to. default: "main". 🏠
  • events — this hash reference holds the mappings for the events the component generates. callers can set these values to either event handler names (strings) or to callbacks (code references). if you give it names, the events get thrown at the alias you specified; if you give it a code reference, it just gets called directly. the allowable keys are all listed below in the "Event Callbacks" section.
    • exempli gratia —
$p = POE::Component::Child->new(
        alias => "my_session",
        events => { stdout => "my_out", stderr => \&my_err }
        );

in that example up there, any output the children produce on stdout generates an event my_out for the my_session session, while output on stderr causes a call to my_err(). two channels, two destinies. 🫶

  • writemap — this one can be set to a hash reference containing a mapping of method names to strings that get written to the client.
    • exempli gratia —
writemap => { quit => "bye", louder => "++" }

in that example, a caller can issue a call to $self-quit()>, and the string "bye" gets written to the client — or $self-louder()> to have the client receive the string "++". iconic behaviour honestly. 🎤

  • conduit — if you leave it unspecified, POE::Wheel::Run assumes "pipe". alternatively you can provide "pty", in which case no stderr events will be fired. 🚫
  • debug — setting this parameter to a true value generates debugging output. useful mostly to hacks. (their words, not mine, but fr fr.) 🐛

💜 run {array}

this method needs an array indicating the command (and its optional parameters) to run. the command and its parameters can also be passed as a single string. the method returns the id of the wheel, which you need when you're running several commands simultasneously. 🏃♀️🏃♀️

before calling this function, the caller may set the stdio filter to a value of their choice. the example below shows the default that's used:

$p->{StdioFilter} = POE::Filter::Line->new(OutputLiteral => '\n');

🍓 write {array}

this method is how you send input to the child. it can accept an array, and that array gets passed through as such to the child. 📨

🌸 quit [command]

this method requests that the currently selected wheel quit. you can pass an optional command string which gets sent to the child — super useful for graceful shutdown of interactive children, e.g. the ftp command understands "bye" to quit. ✌️

if no command is specified, the system uses whatever string was passed as the quit item in the writemap hash argument to new(). if that too was left unspecified, a kill is issued. please note: if the child is instructed to quit, it will not generate a died event, but a done instead — even when it's hard killed. 😭

please note that quitting all children will not shut the component down — for that, use the shutdown method. don't get it twisted.

🔥 kill [HARD/SIG = TERM, NODIE = 0]

instructs the component to send the child a signal. by default the TERM signal is sent, but the SIG named parameter lets the caller specify literally anything else. if HARD => 1 is specified, a hard kill (-9) is done and any specific signal you passed gets ignored.

note that by default, killing the child generates a died event (not a done) — unless the named parameter NODIE is passed a true value.

additionally, note that kills are done immediately, not scheduled. no waiting around. 💀

  • exempli gratia —
$obj->kill();                       # a TERM signal is sent
$obj->kill(HARD => 1);              # a -9 gets sent
$obj->kill(SIG => 'INT');           # obvious
$obj->kill(HARD => 1, NODIE => 1);  # hard kill w/o a C<died> event

🧚 shutdown

this method causes the component to kill all children and shut down. it's giving everybody out of the pool. 🌊

⭐ attr <key> [val]

gets or sets the value of a certain key. values inside of hashes can be specified by separating the keys with slashes, e.g. $self->attr("events/quit", "bye"); whould store "bye" in {events}{quit} inside of the object. 🗂️

🌈 wheelid

used to set the current wheel for the other methods to work with. please note that ->write(), ->quit() and ->kill() will work on the wheel most recently created. i you wish to work with a previously created wheel, set it with this method. 🎡

💖 wheel [id]

returns a reference to the current wheel. if an id is provided, then that wheel is returned. 🫶

👑 EVENTS / CALLBACKS 👑

events are are thrown at the session indicated as alias, and may be specified using the callbacks argument to the new() method. if no such preference is indicated, the default event names listed below are used. whenever callbacks are specified, they're called directly instead of generating an event.

event handlers get passed two arguments: ARG0, which is a reference to the component instance being used (i.e. $self), and ARG1, a hash reference containing the wheel id being used (as wheel) plus values specific to the event. callbacks get passed the same arguments but as @_[0,1] instead. 🎁

🌸 stdout

this event is fired upon any generation of output from the client. the output produced is provided in "out", e.g.:

$_[ARG1]->{out}

🦋 stderr

works exactly as with stdout but for the error channel. same energy, different pipe. 🚨

🎀 done

fired upon termination of the child, including such cases as when the child is asked to quit or when it ends naturally (as with non-interactive children). please note that this event is fired when _both_ the OS death signal has been received _and_ the child has closed its output pipes. (this also holds true for the died event described below.) ✨

💀 died

fired upon abnormal ending of a child. this event is generated only for interactive children who terminate without having been asked to. inclusion of the "died" key in the "callbacks" hash passed to ->new() qualifies a process for receiving this event and distinguishes it as interactive. this event is mutually exclusive with "done". can't have both, babe. 🙅♀️

🍓 error

this event is fired upon generation of any error by the child. arguments passed include: syscall, err (the numeric value of the error), error (a textual description), and fh (the file handle involved). 📋

💜 AUTHOR 💜

Erick Calder <ecalder@cpan.org>

🫶 ACKNOWLEDGEMENTS 🫶

1e6 thx pushed to Rocco Caputo for suggesting this needed putting together, for giving me the privilege to do it, and for all the late night help. a whole million thanks, literally. 🌙✨

🌈 AVAILABILITY 🌈

this module may be found on the CPAN. additionally, both the module and its RPM package are available from:

http://perl.arix.com

🌸 SUPPORT 🌸

thank you notes, expressions of aggravation and suggestions may be mailed directly to the author :) 📬

Copyright (c) 2002-2003 Erick Calder.

this product is free and distributed under the Gnu Public License (GPL). a copy of this license was included in this distribution in a file called LICENSE. if for some reason this file was not included, please see http://www.gnu.org/licenses/ to obtain a copy of this license. 📜

$Id: Child.pm,v 1.39 2005/12/30 04:14:38 ekkis Exp $

😭 POD ERRORS 😭

hey! the above document had some coding errors, which are explained below:

  • Around line 388:
    • '=item' outside of any '=over'
  • Around line 427:
    • You forgot a '=back' before '=head2'

and that's the whole page, bestie!! this came to you from perl v5.42.0, dated 2025-07-25, filed under Child(3) — go forth and manage those children responsibly 💖✨🎀🦋🌸💅🫶

📦 where this page comes from