NAME

Ubic::Daemon - daemon management utilities

VERSION

version 1.58

SYNOPSIS

    use Ubic::Daemon qw(start_daemon stop_daemon check_daemon);

    start_daemon({bin => '/bin/sleep', pidfile => "/var/lib/something/pid"});
    stop_daemon("/var/lib/something/pid");

    $daemon_status = check_daemon("/var/lib/something/pid");

DESCRIPTION

This module provides functions which let you daemonize any binary or perl coderef.

Main source of knowledge if daemon is still running is pidfile, which is locked all the time after daemon was created.

Note that pidfile format is unreliable and can change in future releases (it's actually even not a file, it's a dir with several files inside it), so if you need to get daemon's pid, don't try to read pidfile directly, use "check_daemon()" function.

stop_daemon($pidfile)

stop_daemon($pidfile, $options)

Stop daemon which was started with $pidfile.

It sends SIGTERM to process with pid specified in $pidfile until it will stop to exist (according to "check_daemon()" method).

If it fails to stop process after several seconds, exception will be raised (this should never happen, assuming you have enough grants).

Options:

timeout: Number of seconds to wait before raising exception that daemon can't be stopped.

Return value: "not running" if daemon is already not running; "stopped" if daemon is stopped by SIGTERM.

start_daemon($params)

Start daemon.

Throws exception if anything fails.

Successful completion doesn't mean much, though, since daemon can fail any moment later, and we have no idea when its initialization stage finishes.

Parameters:

bin

Binary which will be daemonized.

Can be string or arrayref with arguments. Arrayref-style values are recommended in complex cases, because otherwise "exec()" can invoke sh shell which will immediately exit on sigterm.

function

Function which will be daemonized. One and only one of function and bin must be specified.

Function daemonization is a dangerous feature and will probably be deprecated and removed in future.

name

Name of guardian process. Guardian will be named "ubic-guardian $name".

If not specified, bin's value will be used, or "anonymous" when daemonizing perl code.

pidfile

Pidfile is a dir in local filesystem which will be used as a storage of daemon's info.

It will be created if necessary, assuming that its parent dir exists.

stdout

Write all daemon's output to given file. If not specified, all output will be redirected to "/dev/null".

stderr

Write all daemon's error output to given file. If not specified, all stderr will be redirected to "/dev/null".

ubic_log

Optional filename of ubic log. Log will contain some technical information about running daemon.

If not specified, this logging facility will be disabled.

cwd

Change working directory before starting a daemon. Optional.

env

Modify environment before starting a daemon. Optional. Must be a plain hashref if specified.

proxy_logs

Boolean flag.

If enabled, "ubic-guardian" will replace daemon's stdout and stderr filehandles with pipes, proxy all data to the log files, and reopen them on SIGHUP.

There're two reasons why this is not the default:

1) It's a bit slower than allowing the daemon to write its logs itself;

2) The code is new and more complex than the simple "spawn the daemon and wait for it to finish".

On the other hand, using this feature allows you to reopen all logs without restarting the service.

credentials

Set given credentials before execing into a daemon. Optional, must be an "Ubic::Credentials" object.

start_hook

Optional callback that will be executed before execing into a daemon.

This option is a generalization of cwd and env options. One useful application of it is setting ulimits: they won't affect your main process, since this hook will be executed in the context of double-forked process.

Note that hook is called *before* the credentials are set. Raising the ulimits won't work otherwise.

term_timeout

Number of seconds to wait between sending SIGTERM and SIGKILL to the daemon on stopping.

Zero value means that guardian will send SIGKILL to the daemon immediately.

Default is 10 seconds.

check_daemon($pidfile): Check whether daemon is running.
Returns instance of Ubic::Daemon::Status class if daemon is alive, and false otherwise.

BUGS AND CAVEATS

Probably. But it definitely is ready for production usage.

This module is not compatible with Windows by now. It can be fixed by implementing correct "Ubic::Daemon::OS::Windows" module.

If you wonder why there are "ubic-guardian" processes in your "ps" output, see Ubic::Manual::FAQ, answer is there.

AUTHOR

Vyacheslav Matyukhin <mmcleric@yandex-team.ru>

COPYRIGHT AND LICENSE

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