Provided by: libmojo-ioloop-readwriteprocess-perl_0.33-1_all bug

NAME

       Mojo::IOLoop::ReadWriteProcess::Container - (kinda) Pure Perl containers.

SYNOPSIS

           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $container = container(
             pid_isolation => 1,  # Best-effort, as depends on where you run it (you need CAP_SYS_ADMIN)
             subreaper => 1,
             group   => "my_org",
             name    => "my_process",
             process => process(
               sub {
                 # Exec, fork ..
                 process(sub { warn "\o/"; sleep 42;  })->start;
                 process(sub { warn "\o/"; sleep 42; })->start;
                 process(
                   sub {
                     process(
                       sub {
                         process(sub { warn "\o/"; sleep 42; })->start;
                         warn "\o/";
                         sleep 400;
                         warn "\o/";
                       })->start;
                     warn "Hey";
                     sleep 42;
                     warn "\o/";
                   })->start;
                 sleep 42;
               }
             )->separate_err(0));

           $container->start();
           $container->is_running;
           $container->stop;

           my @procs = $container->cgroups->first->processes;
           $container->cgroups->first->pid->max(300);

           $container->process->on(stop => sub { print "Main container process stopped!" });

DESCRIPTION

       Mojo::IOLoop::ReadWriteProcess::Container ties anonymous functions or a
       Mojo::IOLoop::ReadWriteProcess object to different sets of
       Mojo::IOLoop::ReadWriteProcess::CGroup implementations.

       When the "pid_isolation" attribute is set, it needs special permissions (CAP_SYS_ADMIN
       capabilities).  This module uses features that are only available on Linux, and requires
       cgroups and capability (CAP_SYS_ADMIN) for unshare syscalls to achieve pid isolation.

EVENTS

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

   start
        $container->on(start => sub {
          my ($process) = @_;
           ...
        });

       Emitted when the container starts.

   stop
        $container->on(stop => sub {
          my ($container) = @_;
          ...
        });

       Emitted when the container stops.

   process_error
        $container->on(container_error => sub {
          my ($e) = @_;
          my @errors = @{$e};
        });

       Emitted when the container produce errors.

METHODS

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

   start
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container( name=>"test", process => sub { print "Hello!" });
           $c->start();

       Starts the container, it's main process is a Mojo::IOLoop::ReadWriteProcess, contained in
       the "process()" attribute. On stop it will terminate every process included in the cgroups
       attribute.

   is_running
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container( name=>"test", process => sub { print "Hello!" });
           $c->is_running();

       Returns 1 if the container is running.

   stop
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
           $c->stop();

       Stops the container and kill all the processes belonging to the cgroup.  It also registers
       all the unknown processes to the current Mojo::IOLoop::ReadWriteProcess::Session.

   wait_stop
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
           $c->wait_stop();

       Wait before stopping the container.

   wait
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
           $c->wait();

       Wait the container to stop

   migrate_process
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container( name=>"test", process => sub { print "Hello!" })->start;
           $c->migrate_process(42);

       Migrate the given process to the container cgroup.

ATTRIBUTES

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

   name
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);
           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
           use Mojo::Collection 'c';

           my $container = container( name => "test", process => sub { print "Hello!" } );

           $container->session->on(register => sub { ... });
           $container->start();

       Sets the container name. It creates in the indicated (or default) cgroups a sub-tree with
       the container name.

       This means that cgroups settings can be done also outside of the container object:

           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);

           my $container = container( name => "test", process => sub { print "Hello!" } );

           cgroupv1->from($continer->cgroups->first->_group)->pid->max(100);

       As cgroups are represented by path, you can set options directly from controllers objects
       that are pointing to the same cgroup slice.

   group
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);
           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv2);
           use Mojo::Collection 'c';

           my $container = container( name => "bar", group => "foo", process => sub { print "Hello!" } );
           my $container2 = container( name => "bar2", group => "foo", process => sub { print "Hello!" } );

           $container->start();
           $container2->start();

           my $group_cgroup = cgroupv2->from($container2->cgroups->first->parent);

           $group_cgroup->pid->max(200);

       Sets the container group. If containers are sharing the same group they will inherit the
       same CGroup parent path, in such way it is possible to create controllers pointing to it
       and set specific options for the whole group.

   pid_isolation
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);
           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
           use Mojo::Collection 'c';

           my $container = container( pid_isolation => 1, process => sub { print "Hello!" } );

           $container->session->on(register => sub { ... });
           $container->start();

       If set, the process will see itself as PID 1. It needs CAP_SYS_ADMIN capabilities set on
       the executable (or run as root).

   pre_migrate
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $container = container( pre_migrate => 1, process => sub { print "Hello!" } );

           $container->session->on(register => sub { ... });
           $container->start();

       If set, the process will migrate itself into the cgroup.

   clean_cgroup
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $container = container( clean_cgroup => 1, process => sub { print "Hello!" });

           $container->session->on(register => sub { ... });
           $container->start();

       If set, attempts to destroy the cgroup after the process terminated its execution.

   subreaper
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container(subreaper => 1, name=>"test", process => sub { print "Hello!" });
           $c->start();

       Enable subreaper mode inside the child process.

   process
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container(process => sub { print "Hello!" });
           my $c = container(process => sub { print "Hello!" });

           $c->start();

       The process to run. It can be an anonymous function or a Mojo::IOLoop::ReadWriteProcess
       object.

   namespace
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container(process => sub { print "Hello!" });
           $c->namespace->unshare(0); # All
           $c->start();

       Set/Return Mojo::IOLoop::ReadWriteProcess::Namespace object. It's main use is to invoke
       syscalls.

   session
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);

           my $c = container(process => process(sub { print "Hello!" }));
           $c->session->on(register => sub { ... });
           $c->start();

       Returns/Set the Mojo::IOLoop::ReadWriteProcess::Session singleton object.

   unshare
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);
           use Mojo::IOLoop::ReadWriteProcess::Namespace qw( CLONE_NEWPID CLONE_NEWNS );

           my $c = container( unshare=> CLONE_NEWPID | CLONE_NEWNS, process => sub { print "Hello!" } );
           $c->session->on(register => sub { ... });
           $c->start();

       Returns/Set the unshare syscall options. See man unshare(2) for further documentation.

   cgroups
           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);
           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
           use Mojo::Collection 'c';

           my $container = container(process => sub { print "Hello!" });
           $container->cgroups( c(cgroupv1(controller => 'pids'), cgroupv1(controller => 'memory')) );

           $container->session->on(register => sub { ... });
           $container->start();

       Returns/Set a Mojo::Collection collection of CGroups where the process should belong to.
       If used with a single CGroup, you don't need to pass the Mojo::Collection  object:

           use Mojo::IOLoop::ReadWriteProcess::Container qw(container);
           use Mojo::IOLoop::ReadWriteProcess qw(process);
           use Mojo::IOLoop::ReadWriteProcess::CGroup qw(cgroupv1);
           use Mojo::Collection 'c';

           my $container = container(cgroups=> cgroupv1(controller => 'pids'), process => sub { print "Hello!" });

           $container->session->on(register => sub { ... });
           $container->start();

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>

perl v5.36.0                                2022-12Mojo::IOLoop::ReadWriteProcess::Container(3pm)