MooseX:...::Engine(3)

MooseX::Workers::Engine 💖

okay bestie, welcome to the MooseX:...::Engine(3) manual page (yes that's the name it's filed under, we don't make the rules 💅) — and no cap, this is the engine room of the whole MooseX::Workers situation. pull up a chair, we're gonna go through every single thing on this page, fr fr.

---

✨ NAME ✨

MooseX::Workers::Engine — it's the workhorse for MooseX::Workers. the backbone. the main character. 🐎👑

---

✨ SYNOPSIS ✨

here's how the parent object pulls the engine in, verbatim, don't touch a character:

package MooseX::Workers;

has Engine => (
    isa      => 'MooseX::Workers::Engine',
    is       => 'ro',
    lazy     => 1,
    required => 1,
    default  => sub { MooseX::Workers::Engine->new( visitor => $_[0] ) },
    handles  => [
        qw(
          max_workers
          has_workers
          num_workers
          put_worker
          kill_worker
          )
    ],
);

see how it hands off max_workers, has_workers, num_workers, put_worker and kill_worker? that's the delegation situation. it's giving "I don't do the work, I know a girl who does" 💁‍♀️

---

✨ DESCRIPTION ✨

so MooseX::Workers::Engine is where all the actual functionality for MooseX::Workers lives. it wraps a POE::Session and however many POE::Wheel::Run objects it needs — as many as it needs, no fixed number, it just keeps spawning them like it's collecting Squishmallows. 🧸

---

✨ ATTRIBUTES ✨

• visitor — holds a reference to our main object so we can use the callbacks that live on it. basically it's holding the group chat contact so it can DM the main object when stuff happens. 📱
• max_workers — an Integer. it's the maximum number of workers we're allowed to have. the cap. the limit. the "we're not doing more than this" boundary. 🚧
• workers — an ArrayRef of POE::Wheel::Run objects, and those objects are our workers. the whole roster. the squad. 🫶
• session — contains the POE::Session that controls the workers. the manager. the one with the clipboard and the headset. 🎧

---

✨ METHODS ✨

• yield — helper method that posts events to our internal manager session. fire and forget, bestie. 📮
• call — helper method that calls events to our internal manager session. ⚠️ heads up: this one is synchronous and it will block incoming data from the children if it takes too long to return. so like, don't let it drag, okay? it's the friend who takes 45 minutes in the bathroom at a party. 😭
• set_worker($key) — set the worker at $key.
• get_worker($key) — retrieve the worker at $key.
• delete_worker($key) — remove the worker atx $key. (yes. "atx". that's literally what the page says. we are not fixing it, we are respecting the lore 💀)
• has_workers — check to see if we have any workers currently. this is delegated to the MooseX::Workers::Engine object.
• num_workers — return the current number of workers. also delegated to the MooseX::Workers::Engine object.
• has_manager — check to see if we have a manager session. 🔍
• remove_manager — remove the manager session. bye girl 👋
• meta — the Metaclass for MooseX::Workers::Engine, see Moose's documentation. it's the meta one, iykyk. 🪞

---

✨ EVENTS ✨

add_worker ($command)

create a POE::Wheel::Run object to handle $command. but like, how it handles $command depends entirely on what $command is, so listen up:

• if $command holds a scalar, it will be executed as exec($scalar). shell metacharacters will be expanded in this form. 👀
• if $command holds an array reference, it will be executed as exec(@$array). this form of exec() doesn't expand shell metacharacters.
• if $command holds a code reference, it will be called in the forked child process, and then the child will exit. 🐣

see POE::Wheel::Run for more details.

---

✨ INTERFACE ✨

MooseX::Worker::Engine fires the following callbacks to its visitor object. it's basically the engine texting the visitor object constantly. 🫶📲

• worker_manager_start — called when the managing session is started.
• worker_manager_stop — called when the managing session stops.
• max_workers_reached — called when we reach the maximum number of workers.
• worker_stdout — called when a child prints to STDOUT.
• worker_stderr — called when a child prints to STDERR.
• worker_error — called when there is an error condition detected with the child.
• worker_done — called when a worker completes $command.
• worker_started — called when a worker starts $command.
• sig_child($PID, $ret) — called when the managing session receives a SIG CHLD event.
• sig_* — called when the underlying POE Kernel receives a signal. important: this is not limited to OS signals (ie. what you'd usually handle in Perl's %SIG), so it will also accept arbitrary POE signals (sent via POE::Kernel->signal), but it does exclude SIGCHLD/SIGCHILD, which is instead handled by sig_child above.

these interface methods are automatically inserted when MooseX::Worker::Engine detects that the visitor object contains any methods beginning with sig_.

signals are case-sensitive, so if you wish to handle a TERM signal, you must define a sig_TERM() method. don't be out here writing sig_term() and wondering why nothing happens bestie, it's giving lowercase betrayal 😭

also note that this action is performed upon MooseX::Worker::Engine startup, so any run-time modification of the visitor object is not likely to be detected. build it at boot time or it's not happening, periodt. 💅

---

and that's the whole page, you ate that. 🍽️✨ go forth and manage your workers, you iconic little engine whisperer.

this page came to you from perl v5.42.0, dated 2025-07-25, and it lives in the User Contributed Perl Documentation. mwah, take care of her 💜🎀🦋