.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Acme::Spork 3"
.TH Acme::Spork 3 "2009-04-02" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Acme::Spork \- Perl extension for spork()ing in your script
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    use Acme::Spork;
\&    my $spork_pid = spork(\e&long_running_code, @ARGV) 
\&        or die "Could not fork for spork: $!";
\&    print "Long running code has been started as PID $spork_pid, bye!\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A spork in the plastic sense is a fork combined with a spoon. In programming I've come to call a \fIspork()\fR a \fIfork()\fR that does more than just a fork.
.PP
I use it to describe when you want to \fIfork()\fR to run some long running code but immediately return to the main program instead of waiting for it.
.SH "\fIspork()\fP"
.IX Header "spork()"
The first argument is a code ref that gets executed and any other args are passed to the call to the code ref.
.PP
.Vb 1
\&    #!/usr/bin/perl
\&
\&    use strict;
\&    use warnings;
\&    use Acme::Spork;
\&
\&    print 1;
\&    spork( 
\&        sub { 
\&            sleep 5;
\&            open my $log_fh, \*(Aq>>\*(Aq, \*(Aqspork.log\*(Aq, or die "spork.log open failed: $!";
\&            print {$log_fh} "I am spork hear me spoon\en"; 
\&            close $log_fh;
\&        },
\&    ) or die qq{Couldn\*(Aqt fork for spork: $!};
\&    print 2;
.Ve
.PP
This prints out \*(L"12\*(R" immediately and is done running, now if you tail \-f spork.log you'll see \*(L"I am spork hear me spoon\en\*(R" get written to it 4 or 5 seconds later by the \fIspork()\fRed process :)
.PP
\&\fIspork()\fR returns the \s-1PID\s0 of the \fIspork()\fRed process so you can keep track of them and do what you need with it.
.PP
If it returns false then fork failed so you can:
.PP
.Vb 7
\&    if(spork(\e&foo)) {
\&        print "I am spork here me spoon\en";
\&    }
\&    else {
\&        print "Could not fork for spork: $!";
\&    }
\&    my $spork_pid = spork(\e&foo) or die "Could not fork for for spork: $!";
.Ve
.ie n .SS "%reopen_stdfhs_to"
.el .SS "\f(CW%reopen_stdfhs_to\fP"
.IX Subsection "%reopen_stdfhs_to"
You can now have spork reopen one or more of \s-1STDIN, STDOUT, STDERR.\s0
You define how this is handled in the Acme::Spork hash '%reopen_stdfhs_to'
.PP
The key is the STD* handle (any other values are simply ignored).
.PP
The value is an array reference of arguments to \fIopen()\fR.
.PP
Its always a good idea to \fIlocal()\fRize it as well (and specify all 3 handles, otherwise you may get some strange warnings and behavior):
.PP
.Vb 6
\&    local %Acme::Spork::reopen_stdfhs_to = (
\&         STDIN  => [qw(< /dev/null)],
\&         STDOUT => [qw(> /dev/null)],
\&         STDERR => [qw(> &STDOUT)],
\&    );
\&    spork(...)
.Ve
.PP
or you can have it set to the value above globally like so:
.PP
.Vb 3
\&    use Acme::Spork qw(\-reopen_stdfhs);
\&    ...
\&    spork(...)
.Ve
.SS "\fIsetsid()\fP"
.IX Subsection "setsid()"
Say you have a custom module that is a subset of \s-1POSIX\s0 functions that includes \fIsetsid()\fR and you'd rather use that one instead of bringing in all of \s-1POSIX.\s0
.PP
Just define Acme::Spork::setsid ()
.PP
.Vb 5
\&   sub Acme::Spork::setsid {
\&       require POSIX::Subset;
\&       POSIX::Subset::setsid();  
\&   }
\&   my $pid = spork(...);
.Ve
.PP
or if you already have the module loaded:
.PP
.Vb 2
\&  *Acme::Spork::setsid = *POSIX::Subset::setsid;
\&   my $pid = spork(...);
.Ve
.PP
It will use your \fIsetsid()\fR instead and \s-1POSIX\s0 will not be brought in. If it doesn't actually \fIsetsid()\fR then you just broke yourself so don't do that.
.SH "\fIdaemonize()\fP"
.IX Header "daemonize()"
Since many daemons need to spork a child process when a request is received I've included a cheat function to daemonize your script execution.
.PP
Its simply a wrapper for Proc::Daemon::Init.
.PP
.Vb 1
\&    use Acme::Spork qw(daemonize);
\&
\&    # make sure we are the only one running:
\&    use Unix::Pid \*(Aq/var/run/this.pid\*(Aq;
\&
\&    # if so make me a daemon:
\&    daemonize();
\&
\&    # and redo the pid_file with the new pid
\&    Unix::PID\->new()\->pid_file(\*(Aq/var/run/this.pid\*(Aq) 
\&        or die \*(AqThe PID in /var/run/this.pid is still running.\*(Aq; 
\&
\&    # and handle requests as a server:
\&    while(<$incoming_requests>) {
\&        my $req_pid = spork(\e&handle_request($_));
\&        if($req_pid) {
\&            spork(\e&log_request($_), $req_pid) 
\&                or warn "Could not spork log request $req_pid: $!";
\&        }
\&        else {
\&            warn "Could not spork request: $!";
\&        }
\&    }
.Ve
.SH "\fIdaemonize_without_close_on()\fP"
.IX Header "daemonize_without_close_on()"
Same as \fIdaemonize()\fR except it doesn't get \fIProc::Daemon::Init()\fR's POSIX::close done.
Useful if that happening causes you problems (which it has me...)
.SH "CAVEAT"
.IX Header "CAVEAT"
If you set \f(CW$SIG\fR{\s-1CHLD\s0} to '\s-1IGNORE\s0' all your $?'s will be \-1 (i.e not what you might be expecting)
.SH "EXPORT"
.IX Header "EXPORT"
\&\fIspork()\fR is by default, \fIdaemonize()\fR and \fIdaemonize_without_close_on()\fR can be.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Proc::Daemon is not used unless you call \fIdaemonize()\fR.
.PP
Unix::PID is not used at all in this module except the \fIdaemonize()\fR example. I figured if you were using this module you many be interested in it as well :)
.SH "ATTN modules@perl.org"
.IX Header "ATTN modules@perl.org"
I'd love to have this registered if you could find it in your heart :)
.PP
<http://www.xray.mpe.mpg.de/mailing\-lists/modules/2005\-12/msg00154.html>
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Muey, <http://drmuey.com/cpan_contact.pl>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006 by Daniel Muey
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.