.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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 "Mojo::IOLoop::ReadWriteProcess::Session 3pm"
.TH Mojo::IOLoop::ReadWriteProcess::Session 3pm "2019-01-06" "perl v5.28.1" "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"
Mojo::IOLoop::ReadWriteProcess::Session \- Session manager for handling child processes.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session;
\&    use Mojo::IOLoop::ReadWriteProcess qw(process);
\&
\&    my $session = process()\->session; # or Mojo::IOLoop::ReadWriteProcess::Session\->singleton
\&
\&    $session\->enable; # Modifies your SIG_CHLD
\&
\&    $session\->on(collected => sub { warn "Process ".(shift\->pid)." collected! "});
\&    $session\->on(collected_orphan => sub { warn "Orphan process collected! "});
\&
\&    $session\->enable_subreaper(); # Mark the current process as subreaper
\&    $session\->disable_subreaper(); # Disable subreaper
\&
\&    $session\->reset(); # Resets events and clear the process tables
\&    $session\->clean(); # Stop all processes that result as running and reset
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojo::IOLoop::ReadWriteProcess::Session is a session manager for the collected processes
.SH "EVENTS"
.IX Header "EVENTS"
Mojo::IOLoop::ReadWriteProcess::Session inherits all events from Mojo::EventEmitter and can emit
the following new ones.
.SS "\s-1SIG_CHLD\s0"
.IX Subsection "SIG_CHLD"
.Vb 4
\& $session\->on(SIG_CHLD => sub {
\&   my ($self) = @_;
\&   ...
\& });
.Ve
.PP
Emitted when we receive \s-1SIG_CHLD.\s0
.SS "collected"
.IX Subsection "collected"
.Vb 4
\&    $session\->on(collected => sub {
\&      my ($self, $process) = @_;
\&      ...
\&    });
.Ve
.PP
Emitted when child process is collected and it's return status is available.
.SS "protect"
.IX Subsection "protect"
.Vb 5
\&    $session\->on(protect => sub {
\&      my ($self, $detail) = @_;
\&      my ($cb, $signal) = @$detail;
\&      ...
\&    });
.Ve
.PP
Emitted when protected callbacks are fired.
.SS "collected_orphan"
.IX Subsection "collected_orphan"
.Vb 6
\&    $session\->on(collected_orphan => sub {
\&      my ($self, $process) = @_;
\&      $process\->pid;
\&      $process\->exit_status;
\&      ...
\&    });
.Ve
.PP
Emitted when child process is collected and it's exit status is available.
Note: here are collected processes that weren't created with Mojo::IOLoop::ReadWriteProcess.
.SS "register"
.IX Subsection "register"
.Vb 6
\&    $session\->on(register => sub {
\&      my ($self, $process) = @_;
\&      $process\->pid;
\&      $process\->exit_status;
\&      ...
\&    });
.Ve
.PP
Emitted when a process is registering to a session.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Mojo::IOLoop::ReadWriteProcess::Session inherits all attributes from Mojo::EventEmitter and implements
the following new ones.
.SS "subreaper"
.IX Subsection "subreaper"
.Vb 6
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    session\->enable_subreaper;
\&    my $process = Mojo::IOLoop::ReadWriteProcess\->new(code => sub { print "Hello ".shift() }, args => "User" );
\&    $process\->start();
\&    $process\->on( stop => sub { $_\->disable_subreaper } );
\&    $process\->stop();
\&
\&    # The process will print "Hello User"
.Ve
.PP
Mark the current process (not the child) as subreaper on start.
It's on invoker behalf to disable subreaper when process stops, as it marks the current process and not the
child.
.SS "collect_status"
.IX Subsection "collect_status"
Defaults to \f(CW1\fR, If enabled it will automatically collect the status of the children process.
Disable it in case you want to manage your process child directly, and do not want to rely on
automatic collect status. If you won't overwrite your \f(CW\*(C`SIGCHLD\*(C'\fR handler,
the \f(CW\*(C`SIG_CHLD\*(C'\fR event will be still emitted.
.SS "\fBhandler()\fP"
.IX Subsection "handler()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    session\->handler(sub {});
.Ve
.PP
Default handler for \s-1SIG_CHLD\s0 processing, used when \f(CW\*(C`disable()\*(C'\fR is invoked.
.SH "METHODS"
.IX Header "METHODS"
Mojo::IOLoop::ReadWriteProcess::Session inherits all methods from Mojo::EventEmitter and implements
the following new ones.
.SS "\fBenable()\fP"
.IX Subsection "enable()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    session\->enable();
.Ve
.PP
Sets the \s-1SIG_CHLD\s0 handler.
.SS "\fBdisable()\fP"
.IX Subsection "disable()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    session\->disable();
.Ve
.PP
Disables the \s-1SIG_CHLD\s0 handler and reset with the previous one.
.SS "\fBenable_subreaper()\fP"
.IX Subsection "enable_subreaper()"
.Vb 5
\&    use Mojo::IOLoop::ReadWriteProcess qw(process);
\&    my $p = process()\->enable_subreaper;
\&    # or
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    session\->enable_subreaper;
.Ve
.PP
Mark the current process (not the child) as subreaper.
This is used typically if you want to mark further childs as subreapers inside other forks.
.PP
.Vb 1
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&
\&    my $master_p = process(
\&      sub {
\&        my $p = shift;
\&        $p\->enable_subreaper;
\&
\&        process(sub { sleep 4; exit 1 })\->start();
\&        process(
\&          sub {
\&            sleep 4;
\&            process(sub { sleep 1; })\->start();
\&          })\->start();
\&        process(sub { sleep 4; exit 0 })\->start();
\&        process(sub { sleep 4; die })\->start();
\&        my $manager
\&          = process(sub { sleep 2 })\->subreaper(1)\->start();
\&        sleep 1 for (0 .. 10);
\&        $manager\->stop;
\&        return session\->all\->size;
\&      });
\&
\&    $master_p\->subreaper(1);
\&    $master_p\->on(collect_status => sub { $status++ });
\&
\&    $master_p\->on(stop => sub { shift()\->disable_subreaper });
\&    $master_p\->start();
\&    session\->all\->size();
\&    ....
.Ve
.SS "\fBdisable_subreaper()\fP"
.IX Subsection "disable_subreaper()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess qw(process);
\&    my $p = process()\->disable_subreaper;
.Ve
.PP
Unset the current process as subreaper.
.SS "\fBprctl()\fP"
.IX Subsection "prctl()"
.Vb 3
\&    use Mojo::IOLoop::ReadWriteProcess qw(process);
\&    my $p = process();
\&    $p\->prctl($option, $arg2, $arg3, $arg4, $arg5);
.Ve
.PP
Internal function to execute and wrap the prctl syscall, accepts the same arguments as prctl.
.SS "\fBreset()\fP"
.IX Subsection "reset()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess qw(session);
\&    session\->reset;
.Ve
.PP
Wipe the process tables.
.SS "\fBclean()\fP"
.IX Subsection "clean()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess qw(session);
\&    session\->clean;
.Ve
.PP
Wipe the process tables, but before attempt to stop running procesess.
.SS "\fBall()\fP"
.IX Subsection "all()"
.Vb 3
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $collection = session\->all;
\&    $collection\->size;
.Ve
.PP
Returns a Mojo::Collection of Mojo::IOLoop::ReadWriteProcess that belongs to a session.
.SS "\fBall_orphans()\fP"
.IX Subsection "all_orphans()"
.Vb 3
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $collection = session\->all_orphans;
\&    $collection\->size;
.Ve
.PP
Returns a Mojo::Collection of Mojo::IOLoop::ReadWriteProcess of orphaned processes that belongs to a session.
They are automatically turned into a Mojo::IOLoop::ReadWriteProcess, also if processes were created by \f(CW\*(C`fork()\*(C'\fR.
.SS "\fBall_processes()\fP"
.IX Subsection "all_processes()"
.Vb 3
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $collection = session\->all_processes;
\&    $collection\->size;
.Ve
.PP
Returns a Mojo::Collection of all Mojo::IOLoop::ReadWriteProcess known processes that belongs to a session.
.SS "\fBcontains()\fP"
.IX Subsection "contains()"
.Vb 3
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $collection = session\->contains(13443);
\&    $collection\->size;
.Ve
.PP
Returns true if the pid is contained in any of the process tables.
.SS "\fBresolve()\fP"
.IX Subsection "resolve()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $process = session\->resolve(12233);
.Ve
.PP
Returns the Mojo::IOLoop::ReadWriteProcess process identified by its pid if belongs to the process table.
.SS "\fBorphan()\fP"
.IX Subsection "orphan()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $process = session\->orphan(12233);
.Ve
.PP
Returns the Mojo::IOLoop::ReadWriteProcess process identified by its pid if belongs to the process table of unknown processes.
.SS "\fBregister()\fP"
.IX Subsection "register()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $process = session\->register(\*(Aqpid\*(Aq => Mojo::IOLoop::ReadWriteProcess\->new);
.Ve
.PP
Register the Mojo::IOLoop::ReadWriteProcess process to the session.
.SS "\fBunregister()\fP"
.IX Subsection "unregister()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $process = session\->unregister(123342);
.Ve
.PP
Unregister the corresponding Mojo::IOLoop::ReadWriteProcess with the given pid.
.SS "\fBcollect()\fP"
.IX Subsection "collect()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    my $process = session\->collect(123342 => 0 => undef);
.Ve
.PP
Collect the status for the given pid.
.SS "\fBprotect()\fP"
.IX Subsection "protect()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    use POSIX;
\&
\&    my $return = session\->protect(sub { print "Hello World\en" });
\&
\&    session\->protect(sub { print "Hello World\en" } => SIGTERM);
.Ve
.PP
Try to protect the execution of the callback from signal interrupts.
.SH "EXPORTS"
.IX Header "EXPORTS"
.SS "\fBsession()\fP"
.IX Subsection "session()"
.Vb 2
\&    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
\&    session\->enable_subreaper;
.Ve
.PP
Returns the Mojo::IOLoop::ReadWriteProcess::Session singleton.
.SH "DEBUGGING"
.IX Header "DEBUGGING"
You can set the \s-1MOJO_EVENTEMITTER_DEBUG\s0 environment variable to get some advanced diagnostics information printed to \s-1STDERR.\s0
.PP
.Vb 1
\&    MOJO_EVENTEMITTER_DEBUG=1
.Ve
.PP
Also, you can set \s-1MOJO_PROCESS_DEBUG\s0 environment variable to get diagnostics about the process execution.
.PP
.Vb 1
\&    MOJO_PROCESS_DEBUG=1
.Ve
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (C) Ettore Di Giacinto.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ettore Di Giacinto <edigiacinto@suse.com>