The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojo-IOLoop-ReadWriteProcess-0.16
River stage zero No dependents
5 ++
/ Mojo::IOLoop::ReadWriteProcess::Session

NAME

Mojo::IOLoop::ReadWriteProcess::Session - Session manager for handling child processes.

SYNOPSIS

    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

DESCRIPTION

Mojo::IOLoop::ReadWriteProcess::Session is a session manager for the collected processes

EVENTS

Mojo::IOLoop::ReadWriteProcess::Session inherits all events from Mojo::EventEmitter and can emit the following new ones.

SIG_CHLD

 $session->on(SIG_CHLD => sub {
   my ($self) = @_;
   ...
 });

Emitted when we receive SIG_CHLD.

collected

    $session->on(collected => sub {
      my ($self, $process) = @_;
      ...
    });

Emitted when child process is collected and it's return status is available.

collected_orphan

    $session->on(collected_orphan => sub {
      my ($self, $process) = @_;
      $process->pid;
      $process->exit_status;
      ...
    });

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.

register

    $session->on(register => sub {
      my ($self, $process) = @_;
      $process->pid;
      $process->exit_status;
      ...
    });

Emitted when a process is registering to a session.

ATTRIBUTES

Mojo::IOLoop::ReadWriteProcess::Session inherits all attributes from Mojo::EventEmitter and implements the following new ones.

subreaper

    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"

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.

collect_status

Defaults to 1, 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 SIGCHLD handler, the SIG_CHLD event will be still emitted.

handler()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    session->handler(sub {});

Default handler for SIG_CHLD processing, used when disable() is invoked.

METHODS

Mojo::IOLoop::ReadWriteProcess::Session inherits all methods from Mojo::EventEmitter and implements the following new ones.

enable()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    session->enable();

Sets the SIG_CHLD handler.

disable()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    session->disable();

Disables the SIG_CHLD handler and reset with the previous one.

enable_subreaper()

    use Mojo::IOLoop::ReadWriteProcess qw(process);
    my $p = process()->enable_subreaper;
    # or
    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    session->enable_subreaper;

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.

    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();
    ....

disable_subreaper()

    use Mojo::IOLoop::ReadWriteProcess qw(process);
    my $p = process()->disable_subreaper;

Unset the current process as subreaper.

prctl()

    use Mojo::IOLoop::ReadWriteProcess qw(process);
    my $p = process();
    $p->prctl($option, $arg2, $arg3, $arg4, $arg5);

Internal function to execute and wrap the prctl syscall, accepts the same arguments as prctl.

reset()

    use Mojo::IOLoop::ReadWriteProcess qw(session);
    session->reset;

Wipe the process tables.

clean()

    use Mojo::IOLoop::ReadWriteProcess qw(session);
    session->clean;

Wipe the process tables, but before attempt to stop running procesess.

all()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $collection = session->all;
    $collection->size;

Returns a Mojo::Collection of Mojo::IOLoop::ReadWriteProcess that belongs to a session.

all_orphans()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $collection = session->all_orphans;
    $collection->size;

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 fork().

all_processes()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $collection = session->all_processes;
    $collection->size;

Returns a Mojo::Collection of all Mojo::IOLoop::ReadWriteProcess known processes that belongs to a session.

contains()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $collection = session->contains(13443);
    $collection->size;

Returns true if the pid is contained in any of the process tables.

resolve()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $process = session->resolve(12233);

Returns the Mojo::IOLoop::ReadWriteProcess process identified by its pid if belongs to the process table.

orphan()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $process = session->orphan(12233);

Returns the Mojo::IOLoop::ReadWriteProcess process identified by its pid if belongs to the process table of unknown processes.

register()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $process = session->register(Mojo::IOLoop::ReadWriteProcess->new);

Register the Mojo::IOLoop::ReadWriteProcess process to the session.

unregister()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $process = session->unregister(123342);

Unregister the corresponding Mojo::IOLoop::ReadWriteProcess with the given pid.

collect()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    my $process = session->collect(123342, 0, undef);

Collect the status for the given pid.

EXPORTS

session()

    use Mojo::IOLoop::ReadWriteProcess::Session qw(session);
    session->enable_subreaper;

Returns the Mojo::IOLoop::ReadWriteProcess::Session singleton.

DEBUGGING

You can set the MOJO_EVENTEMITTER_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.

    MOJO_EVENTEMITTER_DEBUG=1

Also, you can set MOJO_PROCESS_DEBUG environment variable to get diagnostics about the process execution.

    MOJO_PROCESS_DEBUG=1

LICENSE

Copyright (C) Ettore Di Giacinto.

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

AUTHOR

Ettore Di Giacinto <edigiacinto@suse.com>