spelling (RT#85351) (committed by ether)

[gitmo/MooseX-Daemonize.git] / lib / MooseX / Daemonize.pm

diff --git a/lib/MooseX/Daemonize.pm b/lib/MooseX/Daemonize.pm
index c7be66a..83680f4 100644 (file)
--- a/lib/MooseX/Daemonize.pm
+++ b/lib/MooseX/Daemonize.pm
@@ -2,8 +2,7 @@ package MooseX::Daemonize;
 use strict;    # because Kwalitee is pedantic
 use Moose::Role;
 use MooseX::Types::Path::Class;
-
-our $VERSION = "0.10";
+use File::Path qw(make_path);
 
 with 'MooseX::Daemonize::WithPidFile',
      'MooseX::Getopt';
@@ -21,6 +20,7 @@ has progname => (
         ( my $name = lc $_[0]->meta->name ) =~ s/::/_/g;
         return $name;
     },
+    documentation => 'the name of the daemon',
 );
 
 has pidbase => (
@@ -31,6 +31,7 @@ has pidbase => (
     required  => 1,
     lazy      => 1,
     default   => sub { Path::Class::Dir->new('', 'var', 'run') },
+    documentation => 'the base for our pid (default: /var/run)',
 );
 
 has basedir => (
@@ -41,6 +42,7 @@ has basedir => (
     required  => 1,
     lazy      => 1,
     default   => sub { Path::Class::Dir->new('/') },
+    documentation => 'the directory to chdir to (default: /)',
 );
 
 has foreground => (
@@ -49,13 +51,15 @@ has foreground => (
     isa         => 'Bool',
     is          => 'ro',
     default     => sub { 0 },
+    documentation => 'if true, the process won\'t background',
 );
 
 has stop_timeout => (
     metaclass => 'Getopt',
     isa       => 'Int',
     is        => 'rw',
-    default   => sub { 2 }
+    default   => sub { 2 },
+    documentation => 'number of seconds to wait for the process to stop, before trying harder to kill it (default: 2 s)',
 );
 
 # internal book-keeping
@@ -81,6 +85,15 @@ has exit_code => (
 sub init_pidfile {
     my $self = shift;
     my $file = $self->pidbase . '/' . $self->progname . '.pid';
+
+    if ( !-d $self->pidbase ) {
+        make_path( $self->pidbase, { error => \my $err } );
+        if (@$err) {
+            confess sprintf( "Cannot create pidbase directory '%s': %s",
+                $self->pidbase, @$err );
+        }
+    }
+
     confess "Cannot write to $file" unless (-e $file ? -w $file : -w $self->pidbase);
     MooseX::Daemonize::Pid::File->new( file => $file );
 }
@@ -200,7 +213,7 @@ sub stop {
     $self->clear_exit_code;
 
     # if the pid is not running
-    # then we dont need to stop
+    # then we don't need to stop
     # anything ...
     if ($self->pidfile->is_running) {
 
@@ -302,9 +315,9 @@ __END__
 
 MooseX::Daemonize - Role for daemonizing your Moose based application
 
-=head1 VERSION
+=head1 WARNING
 
-This document describes MooseX::Daemonize version 0.05
+The maintainers of this module now recommend using L<Daemon::Control> instead.
 
 =head1 SYNOPSIS
 
@@ -338,10 +351,32 @@ This document describes MooseX::Daemonize version 0.05
 
 =head1 DESCRIPTION
 
-Often you want to write a persistant daemon that has a pid file, and responds
+Often you want to write a persistent daemon that has a pid file, and responds
 appropriately to Signals. This module provides a set of basic roles as an
 infrastructure to do that.
 
+=head1 CAVEATS
+
+When going into background MooseX::Daemonize closes all open file
+handles. This may interfere with you logging because it may also close the log
+file handle you want to write to. To prevent this you can either defer opening
+the log file until after start. Alternatively, use can use the
+'dont_close_all_files' option either from the command line or in your .sh
+script.
+
+Assuming you want to 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 ...
+    };
+
+
 =head1 ATTRIBUTES
 
 This list includes attributes brought in from other roles as well
@@ -359,6 +394,10 @@ The name of our daemon, defaults to C<$package_name =~ s/::/_/>;
 
 The base for our PID, defaults to C</var/run/>
 
+=item I<basedir Path::Class::Dir | Str>
+
+The directory we chdir to; defaults to C</>.
+
 =item I<pidfile MooseX::Daemonize::Pid::File | Str>
 
 The file we store our PID in, defaults to C<$pidbase/$progname.pid>
@@ -368,6 +407,23 @@ The file we store our PID in, defaults to C<$pidbase/$progname.pid>
 If true, the process won't background. Useful for debugging. This option can
 be set via Getopt's -f.
 
+=item I<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".
+
+=item I<ignore_zombies Bool>
+
+If true, the process will not clean up zombie processes.
+Normally you don't want this.
+
+=item I<dont_close_all_files Bool>
+
+If true, the objects open filehandles will not be closed when daemonized.
+Normally you don't want this.
+
+
 =item I<is_daemon Bool>
 
 If true, the process is the backgrounded daemon process, if false it is the
@@ -478,7 +534,7 @@ Handle a HUP signal. By default calls C<$self->restart()>
 
 =head2 Exit Code Methods
 
-These are overriable constant methods used for setting the exit code.
+These are overridable constant methods used for setting the exit code.
 
 =over 4
 
@@ -520,7 +576,7 @@ L<http://rt.cpan.org>.
 
 =head1 SEE ALSO
 
-L<Proc::Daemon>, L<Daemon::Generic>
+L<Daemon::Control>, L<Proc::Daemon>, L<Daemon::Generic>
 
 =head1 AUTHORS
 
@@ -537,7 +593,7 @@ Some bug fixes sponsored by Takkle Inc.
 
 =head1 LICENCE AND COPYRIGHT
 
-Copyright (c) 2007-2010, Chris Prather C<< <chris@prather.org> >>. Some rights
+Copyright (c) 2007-2011, Chris Prather C<< <chris@prather.org> >>. Some rights
 reserved.
 
 This module is free software; you can redistribute it and/or