view release on metacpan or  search on metacpan

lib/Linux/Event/Fork.pm  view on Meta::CPAN

  my $flags = fcntl($fh, F_GETFL, 0);
  croak "fcntl(F_GETFL): $!" if !defined $flags;
  my $ok = fcntl($fh, F_SETFL, $flags | O_NONBLOCK);
  croak "fcntl(F_SETFL,O_NONBLOCK): $!" if !$ok;
  return;
}

1;


__END__

=head1 NAME

Linux::Event::Fork - Child process management integrated with Linux::Event

=head1 SYNOPSIS

  use v5.36;
  use Linux::Event;
  use Linux::Event::Fork;

  my $loop   = Linux::Event->new;
  my $forker = Linux::Event::Fork->new($loop,
    max_children => 4,  # 0 = unlimited
  );

  my $h = $forker->spawn(
    cmd => [ $^X, '-we', 'print "hello\n"; exit 0' ],

    on_stdout => sub ($child, $chunk) {
      print $chunk;
    },

    on_exit => sub ($child, $exit) {
      printf "pid=%d exited=%d code=%d\n",
        $exit->pid, $exit->exited, ($exit->exited ? $exit->code : -1);
      $loop->stop;
    },
  );

  if ($h->isa('Linux::Event::Fork::Request')) {
    warn "queued\n";
  }

  $loop->run;

=head1 DESCRIPTION

Linux::Event::Fork runs child processes while integrating their lifecycle and
I/O streams (stdout/stderr/stdin) with a L<Linux::Event> loop.

Features:

=over 4

=item *
Nonblocking stdout/stderr capture (chunk callbacks)

=item *
Optional streaming stdin (parent -> child)

=item *
Timeout support with optional escalation to SIGKILL

=item *
Bounded parallelism (max_children) with queueing

=item *
Drain callback when all work completes

=item *
Cancel queued requests (bulk or per-request)

=item *
Introspection (running/queued/max_children)

=back

=head1 EXECUTION MODEL

All C<on_*> callbacks run in the B<parent process>, inside the event loop.

Only the C<child =E<gt> sub { ... }> callback runs in the B<child process>.

Stream directions:

  stdin   : parent -> child
  stdout  : child  -> parent
  stderr  : child  -> parent

There is no "on_stdin" callback. Stdin is a write stream to the child.

=head1 CONSTRUCTOR

=head2 new($loop, %args)

  my $forker = Linux::Event::Fork->new($loop,
    max_children => 4,   # optional (default 0 = unlimited)
  );

Constructs a forker bound to a specific event loop.

Arguments:

=over 4

=item max_children => $n

Maximum number of concurrently running children. C<0> means unlimited.

=back

=head1 METHODS

=head2 loop

  my $loop = $forker->loop;

Returns the underlying L<Linux::Event> loop.

lib/Linux/Event/Fork.pm  view on Meta::CPAN

=item * L<Linux::Event::Fork::Request>

If queued due to C<max_children>.

=back

=head3 spawn options

Exactly one of:

=over 4

=item cmd => \@argv

Execs the given argv in the child.

=item child => sub { ... }

Runs the coderef in the child process. If it returns, the child exits with 127.

=back

Optional:

=over 4

=item on_start => sub ($child) { ... }

Called in the parent after the child handle is created (and before the loop
has necessarily observed any I/O).

=item on_stdout => sub ($child, $chunk) { ... }

Called in the parent when the child writes to stdout.

=item on_stderr => sub ($child, $chunk) { ... }

Called in the parent when the child writes to stderr.

=item on_exit => sub ($child, $exit) { ... }

Called in the parent after the child has fully exited. C<$exit> is a
L<Linux::Event::Fork::Exit>.

=item capture_stdout => $bool

Force stdout capture on/off.
Default: true if C<on_stdout> is provided, otherwise false.

=item capture_stderr => $bool

Force stderr capture on/off.
Default: true if C<on_stderr> is provided, otherwise false.

=item stdin => $string

If provided, writes this string to the child's stdin after start.

=item stdin_pipe => $bool

If true, keeps stdin open for streaming writes using the child handle.
If false (default), stdin is closed after the initial C<stdin> write (if any).

=item timeout => $seconds

Soft timeout. When it fires: calls C<on_timeout> (if any) and sends SIGTERM.

=item on_timeout => sub ($child) { ... }

Called in the parent when C<timeout> fires.

=item timeout_kill => $seconds

If set, after SIGTERM waits this many seconds and then sends SIGKILL if still alive.

=item cwd => $dir

Changes working directory in the child before exec/callback.

=item umask => $mask

Sets umask in the child before exec/callback.

=item clear_env => $bool

If true, clears %ENV in the child before applying C<env>.

=item env => \%env

Merges these variables into %ENV in the child before exec/callback.

=item tag => $string

Opaque tag stored on the child/request handles.

=item data => $scalar

Opaque user data stored on the child/request handles.

=back

=head2 max_children([$n])

  my $n = $forker->max_children;
  $forker->max_children(8);

Get or set the concurrency limit.

C<0> means unlimited.

Increasing the limit may immediately start queued requests.
Decreasing the limit does not affect running children; it only limits future starts.

=head2 running

  my $n = $forker->running;

Number of children currently running (tracked for capacity control).

=head2 queued