Test2:...ss::IPC(3pm)

📦
version 1.000172 · 8 versions
, in ubuntu stonking

💖 Test2::Harness::IPC — the vibe 💖

okay bestie, welcome to the Perl User Contributed Documentation corner of the internet, specifically the 3pm section, where we talk about Test2::Harness::IPC ✨

🌸 NAME 🌸

Test2::Harness::IPC — it's the base class for modules that control child processes. literally the mom friend of the process-management world 🫶

🦋 DESCRIPTION 🦋

So, this module is the base class for every single part of Test2::Harness that has to do process management. That's it, that's the job. It's the blueprint the other kids inherit from. 👑

🎀 ATTRIBUTES 🎀

  • $pid = $ipc->pid — the root PID of the IPC object. the OG process, if you will.
  • $hashref = $ipc->handlers — custom signal handlers that are specific to this IPC object. your own personal signal-handling stash. 📡
  • $hashref = $ipc->procs — a hashref shaped like $pid => $proc, where $proc is an instance of Test2::Harness::IPC::Proc. every tracked process, filed by pid. slay.
  • $hashref = $ipc->procs_by_cat — a hashref shaped like $category => { $pid => $proc }. same processes, but sorted into little category baskets. 🧺
  • $hashref = $ipc->waiting — a hashref of the processes that have finished but haven't been handled yet. like a group chat of messages you haven't opened.
⚠️ bestie, this is an implementation detail and you should not rely on it. admiring from afar only. 🙈
  • $float = $ipc->wait_time — how long to sleep between loops when you're in a wait cycle. nap length, basically. 😴
  • $bool = $ipc->started — true if the IPC process has started. false if it's still in bed.
  • $ipc->sig_count — implementation detail 🚧 it's used to break out of wait loops whenever signals show up.

💅 METHODS 💅

✨ Lifecycle stuff ✨

  • $ipc->start — starts the IPC management, which means it inserts the signal handlers. glow up initiated.
  • $ipc->stop — stops the IPC management, which means it removes the signal handlers. bye bestie 👋

📣 Signals 📣

  • $ipc->set_sig_handler($sig, sub { ... }) — sets a custom signal handler. this is the safer version of local %SIG{$sig} when you're doing IPC stuff. 🛡️

The callback gets exactly one argument: the name of the signal that was recieved.

  • $ipc->handle_sig($sig) — handles the specified signal. heads up: it will cause a process exit if that signal has no handler. no handler, no mercy, we're out. 💀

🔪 Killing things 🔪

  • $ipc->killall()
  • $ipc->killall($sig)

Kills all the tracked child processes with the given signal. If you don't specify a signal, TERM is used.

🚨 this will not wait on the processes! you must call $ipc->wait() yourself afterwards. don't forget, or you'll be sitting there confused like "where did they go". 😭

🔁 Loop helpers 🔁

  • $ipc->check_timeouts — this one is a no-op on the IPC base class. it gets called on every loop of $ipc->wait. if you subclass the IPC class, you can fill this in so your processes can time out if they need to. DIY time 🎨
  • $ipc->check_for_fork — used a lot internally to check whether this is a forked process. And if it is a forked process, the IPC object gets completely reset with no remaining internal state left over — except the signal handlers. fresh start energy, minus one thing. 🌱
  • $ipc->set_proc_exit($proc, @args) — calls $proc->set_exit(@args). this is called by $ipc->wait. you can override it to add your own custom tasks for when a process exits. cute little farewell party 🎉

⏳ Waiting ⏳

  • $int = $ipc->wait()
  • $int = $ipc->wait(%params)

Waits on processes and returns the number found. default behaviour is non-blocking.

Here are the options, bestie:

  • timeout => $float — if a blocking parameter has been provided, this can break the wait after a timeout. it uses Time::HiRes, so the timeout is in seconds with decimals. precision, we love to see it. ⏱️
  • all => $bool — block until ALL the processes are done. every last one.
  • cat => $category — block until at least 1 process from the category is complete.
  • all_cat => $category — block until ALL processes from the category are complete.
  • block => $bool — block until at least 1 process is complete.

👀 Watching & spawning 👀

  • $ipc->watch($proc) — adds a process to be monitored. keeping an eye on them. 👁️
  • $proc = $ipc->spawn($proc)
  • $proc = $ipc->spawn(%params)

In the first form, $proc is an instance of Test2::Harness::IPC::Proc that provides spawn_params().

In the second form, these are the params you're allowed to use:

  • Anything supported by run_cmd() in Test2::Harness::Util::IPC. ✨
  • process_class => $CLASS — default is Test2::Harness::IPC::Process.
  • command => $command — the program command to call. this one is required, no skipping it.
  • env_vars => { ... } — specify custom environment variables for the new process. give the baby process its own little world 🌍

📚 SOURCE 📚

The source code repository for Test2-Harness lives at http://github.com/Test-More/Test2-Harness/. go lurk, it's iconic. ⭐

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

🌈 AUTHORS 🌈

Chad Granum <exodist@cpan.org>

Copyright 2020 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/

and that's the whole page, bestie 🫶 this shipped as part of perl v5.40.1, dated 2026-05-10, in the Test2:...ss::IPC(3pm) manual. go manage some processes, you absolute icon 💅✨🎀

📦 where this page comes from