The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
JIP-Daemon-0.041
River stage zero No dependents
++
/ JIP::Daemon

NAME

JIP::Daemon - Daemonize server process.

VERSION

This document describes JIP::Daemon version 0.041.

SYNOPSIS

Just run:

    use JIP::Daemon;

    my $proc = JIP::Daemon->new;

    # Send program to backgroung.
    $proc = $proc->daemonize;

    # In the backgroung process:
    $proc->is_detached; # 1
    $proc->try_kill(0); # 1
    printf qq{pid(%s), is_alive(%d), is_detached(%d)\n}, $proc->status;

    # If the program is already a running background job, the daemonize method shall have no effect.
    $proc = $proc->daemonize;

Dry run:

    use JIP::Daemon;

    my $proc = JIP::Daemon->new(dry_run => 1);

    $proc->daemonize;

    # In the same process
    $proc->is_detached; # 0

With logger:

    use Mojo::Log;
    use JIP::Daemon;

    my $proc = JIP::Daemon->new(logger => Mojo::Log->new);

    $proc->daemonize;

With on_fork_callback:

    use JIP::Daemon;

    my $proc = JIP::Daemon->new(
        on_fork_callback => sub {
            # After daemonizing, and before exiting,
            # run the given code in parent process
            print $proc->pid;
        },
    )->daemonize;

ATTRIBUTES

JIP::Daemon implements the following attributes.

pid

    my $pid = $proc->pid;

is_detached

    my $is_detached => $proc->is_detached;

Process is detached from the controlling terminal.

dry_run

    my $dry_run = $proc->dry_run;

Perform a trial run with no changes made (foreground if dry_run).

uid

    my $uid = $proc->uid;

The real user identifier and the effective user identifier for this process.

gid

    my $gid = $proc->gid;

The real group identifier and the effective group identifier for this process.

cwd

    my $cwd = $proc->cwd;

Change the current working directory.

umask

    my $umask = $proc->umask;

Most Daemon processes runs as super-user, for security reasons they should protect files that they create. Setting user mask will prevent unsecure file priviliges that may occur on file creation.

logger

    JIP::Daemon->new(logger => Mojo::Log->new)->logger->info('Hello');

Simple logger, based on Mojo::Log interface.

log_callback

With default callback:

    my $proc = JIP::Daemon->new(logger => Mojo::Log->new);

    # $proc->logger->info('Hello');
    $proc->log_callback->($proc, 'Hello');

    # $proc->logger->info(sprintf 'format %s', 'line');
    $proc->log_callback->($proc, 'format %s', 'line');

With custom callback:

    my $proc = JIP::Daemon->new(
        logger       => Mojo::Log->new,
        log_callback => sub {
            my ($proc, @lines) = @_;
            $proc->logger->debug(@lines);
        },
    );
    $proc->log_callback->($proc, 'Hello');

on_fork_callback

After daemonizing, and before exiting, run the given code in parent process.

devnull

    my $devnull = $proc->devnull;

Returns a string representation of the null device.

stdout

    my $stdout = $proc->stdout;

If this parameter is supplied, redirect STDOUT to file.

stderr

    my $stderr = $proc->stderr;

If this parameter is supplied, redirect STDERR to file.

program_name

    my $program_name = $proc->program_name;

Returns a string with name of the process.

SUBROUTINES/METHODS

new

    my $proc = JIP::Daemon->new;
    my $proc = JIP::Daemon->new(dry_run => 1);

Construct a new JIP::Daemon object.

daemonize

    $proc = $proc->daemonize;

Daemonize server process.

reopen_std

    $proc = $proc->reopen_std;

Reopen STDIN, STDOUT, STDERR to /dev/null.

    my $proc = JIP::Daemon->new(
        stdout => '+>/path/to/out.log',
        stderr => '+>/path/to/err.log',
    );

    $proc = $proc->reopen_std;

The stdout and stderr arguments are file names that will be opened and be used to replace the standard file descriptors. These special modes only work with two-argument form of open.

drop_privileges

    my $proc = JIP::Daemon->new(uid => 1000, gid => 1000, umask => 0, cwd => q{/});
    $proc = $proc->drop_privileges;

Change uid/gid/umask/cwd on demand.

try_kill

    my $is_alive = $proc->try_kill(0);

This is identical to Perl's builtin kill() function for sending signals to processes (often to terminate them).

change_program_name

    my $proc = JIP::Daemon->new(program_name => 'tratata');
    $proc = $proc->change_program_name;

Changes the name of the program.

status

    my ($pid, $is_alive, $is_detached) = $proc->status;

Returns a list of process attributes: PID, is alive, is detached (in backgroung).

DIAGNOSTICS

None.

CONFIGURATION AND ENVIRONMENT

JIP::Daemon requires no configuration files or environment variables.

SEE ALSO

POSIX, Privileges::Drop, Object::ForkAware, Proc::Daemon, Daemon::Daemonize.

AUTHOR

Vladimir Zhavoronkov, <flyweight at yandex.ru>

LICENSE AND COPYRIGHT

Copyright 2015-2018 Vladimir Zhavoronkov.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.