Proc::Guard(3pm)

💖 Proc::Guard 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section of the manual (it's Proc::Guard(3pm), a Perl module page, iykyk) and it is genuinely one of those little gems you're gonna be obsessed with. it's a process runner with the RAII pattern. yes. RAII. we love a resource-cleanup moment. 🎀

---

✨ NAME ✨

Proc::Guard — process runner with RAII pattern

like. it runs a process. and then it guards it. the name ate, honestly. 💅

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready:

use Test::TCP qw/empty_port wait_port/;
use File::Which qw/which/;
use Proc::Guard;

my $port = empty_port();
my $proc = proc_guard(scalar(which('memcached')), '-p', $port);
wait_port($port);

# your code here

# --------------
# or, use perl code
my $proc = proc_guard(sub {
    ... # run this code in child process
});
...

two paths, bestie: run a real command line, or run a lil perl sub in a child process. pick your fighter. 🥊

---

🦋 DESCRIPTION 🦋

Proc::Guard runs a process, and then it destroys it when the perl script exits. that's it. that's the whole personality. set it up, forget it, and it cleans up after itself like the responsible main character it is.

this is useful for testing code working with server process. spin up the server, run your tests, and when the script dips out, the process dips out too. no orphan processes haunting your ps aux. no cap. 👑

---

🔥 FUNCTIONS 🔥

proc_guard(@cmdline|\&code)

this is shorthand for:

Proc::Guard->new(
    command => \@cmdline,
);

or

Proc::Guard->new(
    code => \&code,
);

literally just a cute lil shortcut so you don't have to type Proc::Guard->new every single time. slay. ✨

---

💜 METHODS 💜

my $proc = Proc::Guard->new(%args);

creates and runs a process. and here's the iconic part — the process is terminated when the returned object is being DESTROYed. so like, when your $proc variable goes out of scope or your script ends, bye bye process. it's giving responsible. it's giving RAII. we stan. 🫶

here are the args:

command

Proc::Guard->new(command => '/path/to/memcached');
# or
Proc::Guard->new(command => ['/path/to/memcached', '-p', '11211']);

the command line. give it a plain string, or give it an arrayref if you want to pass args properly. your call, bestie. 🍓

code

Proc::Guard->new(code => sub { ... });

'code' or 'command' is required. like, you gotta pick one. the constructor isn't gonna do the work for you, it's not a mind reader. 💀

auto_start

Proc::Guard->new(auto_start => 0);

start child process automatically or not (default: 1). so if you want to be in charge of when things kick off, set it to 0 and then call start yourself. you're the captain now. ⭐

---

pid

returns process id (or undef if not running). super handy when you need to know who you're dealing with. if it's undef, she's not running, periodt.

---

start

starts process. that's the whole thing. go, baby, go. 🦋

---

stop

stops process. the opposite of start. so satisfying. 🌈

---

💅 VARIABLES 💅

$Proc::Guard::EXIT_STATUS

the last exit status code by "$proc->stop". if "waitpid" failed with an error, this will be set to undef. so check it if you care, and if it's undef — that's the error signal, bestie, don't ignore her. 😭

---

👑 AUTHOR 👑

Tokuhiro Matsuno <tokuhirom AAJKLFJEF GMAIL COM>

(yeah the email is written all funky like that to keep the spam bots away. iconic behaviour, honestly. we respect the hustle. 🙈)

---

🎀 LICENSE 🎀

Copyright (C) Tokuhiro Matsuno

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

---

okay that's the whole page. now go guard some processes, bestie. your test suite is gonna be so clean. 🧚

---

signing off with the deets: this was Proc::Guard(3pm) from the User Contributed Perl Documentation, built for perl v5.36.0, dated 2022-11-19. love that for us. 💖✨