Proc::Daemontools::Service - services that play nicely with daemontools

Proc-Daemontools-Service documentation Contained in the Proc-Daemontools-Service distribution.

Index

Code Index:

NAME

Top

Proc::Daemontools::Service - services that play nicely with daemontools

VERSION

Top

 0.02

SYNOPSIS

Top

  package Foo::Service;
  use base qw(Proc::Daemontools::Service);

  sub svc_up { ... }

  # In other code...

  my $serv = Foo::Service->new;
  $serv->run;

DESCRIPTION

Top

See the daemontools page, at http://cr.yp.to/daemontools.html, and particularly the svc page, at http://cr.yp.to/daemontools/svc.html.

METHODS

Top

new

Takes no arguments (yet).

run

Install signal handlers and call svc_run, which may continue indefinitely.

If svc_run ever finishes, calls exit.

exit

  $serv->exit($exit_status);

Exit, calling svc_exit first if it exists. Default signal handlers call this.

install_handlers

Install signal handlers to queue signals for processing by svc_* methods, below.

NOTE: signal handlers are global. This means that two instances of Proc::Daemontools::Service will fight with each other. Don't do that.

HOOKS

Top

svc_run

Called by run. Your main program body should be here.

svc_exit

Called by exit. Any cleanup should be here. (optional)

SIGNALS

Top

Subclasses should define their own copy of each of these methods. They will be called by Proc::Daemontools::Service as signals are caught.

Names are taken from the full names of svc options.

When called, these methods will be passed a hashref indicating state.

signal

the name of the signal (e.g. TERM)

signum

the number of the signal (e.g. 15)

svc_hangup

svc_alarm

svc_interrupt

svc_terminate

DEFAULT HANDLERS

Top

Uncaught signals will cause your program to exit. If your package defines a svc_exit method, it will be called before exiting (see exit).

The exit value will be the number of the signal that caused program exit.

svc_default

Override this method to provide your own default for the signals listed above.

UNCATCHABLE SIGNALS

Top

KILL

STOP

CONT

Technically CONT isn't uncatchable; however, given that you can't catch STOP, you probably don't want to catch CONT either.

AUTHOR

Top

Hans Dieter Pearcey, <hdp@cpan.org>

BUGS

Top

Please report any bugs or feature requests to bug-proc-daemontools-service@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Proc-Daemontools-Service. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

Top

COPYRIGHT & LICENSE

Top

Copyright 2006 Hans Dieter Pearcey, all rights reserved.

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

Proc-Daemontools-Service documentation Contained in the Proc-Daemontools-Service distribution. 
package Proc::Daemontools::Service;

use warnings;
use strict;
use Config;

my (%SIGNUM, %SIGMETH);
BEGIN {
  my $i = 0;
  for my $name (split ' ', $Config{sig_name}) {
    $SIGNUM{$name} = $i++;
  }

  %SIGMETH = (
    INT  => 'svc_interrupt',
    HUP  => 'svc_hangup',
    TERM => 'svc_terminate',
    ALRM => 'svc_alarm',
  );
}


our $VERSION = '0.02';


sub new {
  my $class = shift;
  die "no arguments to new" if @_;
  return bless {} => $class;
}


sub run {
  my $self = shift;
  $self->install_handlers;
  $self->svc_run;
  $self->exit(0);
}


sub exit {
  my $self = shift;
  if ($self->can('svc_exit')) {
    $self->svc_exit;
  }
  exit(shift);
}


sub install_handlers {
  my $self = shift;
  require sigtrap;
  my @args;
  for my $sig (qw(HUP INT TERM ALRM)) {
    push @args, handler => sub { $self->_handle_signal($sig) } => $sig;
  }
  sigtrap->import(@args);
}

sub _handle_signal {
  my ($self, $signame) = @_;
  my $arg = {
    signame => $signame,
    signum  => $SIGNUM{$signame},
  };
  my $meth = $self->can($SIGMETH{$signame}) || $self->can('svc_default');
  $self->$meth($arg);
}


sub svc_default {
  my ($self, $arg) = @_;
  $self->exit($arg->{signum});
}


1; # End of Proc::Daemontools::Service