NAME

Proc::tored - Service management using a pid file and signals

VERSION

version 0.05

SYNOPSIS

  use Proc::tored;

  my $service = service 'stuff-doer', in '/var/run';

  # Run service
  run { do_stuff() or stop $service } $service
    or die 'existing process running under pid '
          . running $service;

  # Terminate another running process, timing out after 15s
  zap $service, 15
    or die 'stuff_doer pid ' . running $service . ' is being stubborn';

DESCRIPTION

A Proc::tored service is voluntarily managed by a pid file and signals.

EXPORTED SUBROUTINES

Proc::tored is an Exporter. All routines are exported by default.

service

Defines the service by name. The pid file will be created as name.pid.

  my $service = service 'thing', ...;

in

Sets the directory where the pid file will be created.

  my $service = service 'thing', in '/var/run';

run

Starts the service loop, calling the supplied code block until it either returns false or the service is stopped (internally via "stop" or externally via "zap").

  run {
    my $task = get_next_task() or return;
    process_task($task);
    return 1;
  } $service;

stop

Tells the "run" loop to shut down.

  run {
    my $task = get_next_task() or stop $service;
    process_task($task);
    return 1;
  } $service;

running

If the supplied service is running as another process (as found in the pid file), returns the pid of that process. Returns 0 otherwise.

  zap $service if running $service;

zap

Sends a SIGTERM to a running instance of the service, causing it to self-terminate (assuming it is also Proc::tored). Accepts an optional $timeout in fractional seconds, causing zap to wait up to $timeout seconds for the process to exit.

  zap $service, 30
    or die 'timed out after 30s waiting for service to exit';

CAVEATS

Threads

A Proc::tored service voluntarily self-terminates when it receives one of SIGTERM, SIGINT, SIGHUP, or SIGPIPE. On threaded perls, only the main thread receives signals. It is highly likely that a Proc::tored service started outside the main thread will not respond to being "zap"ped by another process.

See catching signals under http://perldoc.perl.org/threads.html#WARNINGS for details.

MSWin32

The same warnings about threads apply to forked processes on MSWin32 perls as a result of fork() being implemented using threads on that platform.

See the notes regarding pseudoprocesses under http://perldoc.perl.org/perlfork.html#kill().

AUTHOR

Jeff Ober <jeffober@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Jeff Ober.

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

cpanm Proc::tored

perl -MCPAN -e shell
install Proc::tored