MooseX...emonize(3pm)

💖 MooseX::Daemonize — bestie edition 💖

okay so you want to write a daemon. a persistent one. with a pidfile. that reacts to signals like a well-behaved little icon. this is the MooseX::Daemonize page from the User Contributed Perl Documentation, and I'm gonna walk you through it like we're texting at 2am. grab a boba. 🧋

---

✨ NAME ✨

MooseX::Daemonize — a Role for daemonizing your Moose based application. that's the whole vibe. 🦋

🌸 VERSION 🌸

version 0.22 — yes queen, we know the number.

✨ SYNOPSIS ✨

this is literally the blueprint, copy it and thrive:

package My::Daemon;
use Moose;

with qw(MooseX::Daemonize);

# ... define your class ....

after start => sub {
    my $self = shift;
    return unless $self->is_daemon;
    # your daemon code here ...
};

# then in your script ...

my $daemon = My::Daemon->new_with_options();

my ($command) = @{$daemon->extra_argv}
defined $command || die "No command specified";

$daemon->start   if $command eq 'start';
$daemon->status  if $command eq 'status';
$daemon->restart if $command eq 'restart';
$daemon->stop    if $command eq 'stop';

warn($daemon->status_message);
exit($daemon->exit_code);

no cap, that's it. with qw(MooseX::Daemonize); and suddenly your class has main character energy as a daemon. 👑

💅 DESCRIPTION 💅

so here's the tea: a lot of the time you wanna write a persistent daemon that has a pid file and responds appropriately to Signals. this module hands you a set of basic roles as the infrastructure to do exactly that. it's giving scaffolding, but make it glamorous. ✨

🚨 WARNING 🚨

bestie. listen. the maintainers of this module now recommend using Daemon::Control instead. so like… it still works, but they're literally telling you to go look at the other one. do with that information what you will. 💀

😭 CAVEATS 😭

okay this part is important so read it slowly.

when it goes into background, MooseX::Daemonize closes all open file handles. and that may interfere with you logging, because it may also close the log file handle you wanna write to. rude, honestly. 🙈

to prevent this you have two options:

• defer opening the log file until after start, or
• use the 'dont_close_all_files' option — either from the command line or in your .sh script.

so say you wanna use Log::Log4perl — for example — you could expand the MooseX::Daemonize example above like this:

after start => sub {
    my $self = shift;
    return unless $self->is_daemon;
    Log::Log4perl->init(\$log4perl_config);
    my $logger = Log::Log4perl->get_logger();
    $logger->info("Daemon started");
    # your daemon code here ...
};

see how the logger gets initialized inside the after start block? that's the whole trick. 🌈

---

👑 ATTRIBUTES 👑

this list includes attributes brought in from other roles as well — we include them here for ease of documentation. all of these attributes are settable through MooseX::Getopt's command line handling, with the exception of is_daemon.

• progname Path::Class::Dir | Str — the name of our daemon. defaults to "$package_name =~ s/::/_/".
• pidbase Path::Class::Dir | Str — the base for our PID. defaults to "/var/run/".
• basedir Path::Class::Dir | Str — the directory we chdir to. defaults to "/".
• pidfile MooseX::Daemonize::Pid::File | Str — the file we store our PID in. defaults to "$pidbase/$progname.pid".
• foreground Bool — if true, the process won't background. useful for debugging. this option can be set via Getopt's -f.
• no_double_fork Bool — if true, the process will not perform the typical double-fork, which is extra added protection from your process accidentally acquiring a controlling terminal. more information can be found by Googling "double fork daemonize".
• ignore_zombies Bool — if true, the process will not clean up zombie processes. normally you don't want this. 🧟
• dont_close_all_files Bool — if true, the objects open filehandles will not be closed when daemonized. normally you don't want this.
• is_daemon Bool — if true, the process is the backgrounded daemon process; if false it is the parent process. this is useful for example in an "after 'start' =" sub { }> block.

NOTE: this option is explicitly not available through MooseX::Getopt.

• stop_timeout — number of seconds to wait for the process to stop, before trying harder to kill it. defaults to 2 seconds. 🔥

these are the internal attributes, which are not available through MooseX::Getopt:

• exit_code Int
• status_message Str

---

⭐ METHODS ⭐

🎀 Daemon Control Methods 🎀

these methods can be used to control the daemon behavior. every effort has been made to have these methods DWIM (Do What I Mean), so that you can focus on just writing the code for your daemon. periodt. 💅

extending these methods is best done with the Moose method modifiers, such as "before", "after" and "around".

• start — setup a pidfile, fork, then setup the signal handlers.
• stop — stop the process matching the pidfile, and unlinks the pidfile.
• restart — literally this is:

$self->stop();
$self->start();

• status
• shutdown

🦋 Pidfile Handling Methods 🦋

• init_pidfile — this method will create a MooseX::Daemonize::Pid::File object and tell it to store the PID in the file "$pidbase/$progname.pid".
• check — this checks to see if the daemon process is currently running by checking the pidfile.
• get_pid — returns the PID of the daemon process.
• save_pid — write the pidfile.
• remove_pid — removes the pidfile.

💜 Signal Handling Methods 💜

• setup_signals — setup the signal handlers. by default it only sets up handlers for SIGINT and SIGHUP. if you wish to add more signals just use the "after" method modifier and add them.
• handle_sigint — handle a INT signal, by default calls "$self-"stop()>
• handle_sighup — handle a HUP signal. by default calls "$self-"restart()>

🌟 Exit Code Methods 🌟

these are overridable constant methods used for setting the exit code.

• OK — returns 0.
• ERROR — returns 1.

🫶 Introspection 🫶

• meta() — the "meta()" method from Class::MOP::Class

---

🍓 DEPENDENCIES 🍓

Moose, MooseX::Getopt, MooseX::Types::Path::Class and POSIX. that's the squad. 💖

💀 INCOMPATIBILITIES 💀

obviously this will not work on Windows. (sorry not sorry. ✨)

🔥 SEE ALSO 🔥

Daemon::Control, Proc::Daemon, Daemon::Generic. go read those too, iykyk. 👑

🧚 THANKS 🧚

Mike Boyko, Matt S. Trout, Stevan Little, Brandon Black, Ash Berlin and the #moose denizens. 💖

some bug fixes sponsored by Takkle Inc.

🌈 SUPPORT 🌈

bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Daemonize> (or bug-MooseX-Daemonize@rt.cpan.org <mailto:bug-MooseX-Daemonize@rt.cpan.org>).

there is also a mailing list available for users of this distribution, at <http://lists.perl.org/list/moose.html>.

there is also an irc channel available for users of this distribution, at "#moose" on "irc.perl.org" <irc://irc.perl.org/#moose>.

👸 AUTHORS 👸

• Stevan Little <stevan.little@iinteractive.com>
• Chris Prather <chris@prather.org>

🌸 CONTRIBUTORS 🌸

• Karen Etheridge <ether@cpan.org>
• Michael Reddick <michael.reddick@gmail.com>
• Yuval Kogman <nothingmuch@woobling.org>
• Ash Berlin <ash@cpan.org>
• Brandon L Black <blblack@gmail.com>
• Jonathan Sailor <jsailor@cpan.org>
• David Steinbrunner <dsteinbrunner@pobox.com>
• Michael Schwern <mschwern@cpan.org>
• Shoichi Kaji <skaji@cpan.org>
• Dave Rolsky <autarch@urth.org>
• Chisel Wright <chisel@chizography.net>

💅 COPYRIGHT AND LICENCE 💅

this software is copyright (c) 2007 by Chris Prather.

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

---

okay that's the whole page, bestie. this was rendered by perl v5.30.0 on 2019-12-22, and it's the MooseX...emonize(3pm) page from the User Contributed Perl Documentation. now go forth and daemonize responsibly. ily. 🫶💖✨