NAME

Linux::Event::Fork::Request - A queued spawn request when max_children is reached

SYNOPSIS

my $h = $loop->fork(
  max_children => 2,   # typically configured via $loop->fork_helper(...)
  cmd => [ ... ],
);

if ($h->isa('Linux::Event::Fork::Request')) {
  # Not started yet; currently queued.
  $h->cancel;     # prevent it from ever starting
}

DESCRIPTION

When bounded parallelism is enabled (max_children) and the limit has been reached, Linux::Event::Fork enqueues the spawn request and returns a Request object.

Requests are started FIFO as capacity frees.

A Request is a handle for queued work. Once it starts, it produces a Linux::Event::Fork::Child.

EXECUTION MODEL

All methods on this object are called from the parent process.

Starting of queued requests happens in the parent, driven by the event loop.

LIFECYCLE

Queued request lifecycle:

fork() called
    |
    +--> queue full
          |
          +--> returns Request
          |
          +--> (later) capacity frees
                  |
                  +--> Request starts
                  |       |
                  |       +--> child() becomes defined
                  |
                  +--> Request is now "started"

Cancel:

Request queued
    |
    +--> cancel()
          |
          +--> request will never start
          +--> no effect on running children

IMPORTANT BEHAVIOR

Spec is copied at enqueue time

The original spawn spec is copied when the Request is created. Later mutation by the caller cannot affect queued work.

(That is intentional and prevents hard-to-debug aliasing.)

METHODS

cancel

my $ok = $req->cancel;

Cancels a queued request (only if it has not yet started).

Returns:

• true on the first successful cancel

• false if it was already canceled

If the request has already started, cancel has no effect on the child.

started

if ($req->started) { ... }

True once the request has started and a child has been spawned.

child

my $child = $req->child;

Returns the Linux::Event::Fork::Child handle once the request starts. Returns undef while still queued (or if canceled before start).

tag

my $tag = $req->tag;

Returns the tag copied from the original spawn request.

data

my $data = $req->data;

Returns the data payload copied from the original spawn request.

RELATIONSHIP TO cancel_queued

Linux::Event::Fork also provides cancel_queued(...) on the helper object. That API cancels queued requests in bulk (typically by tag or predicate).

This object-level cancel() cancels exactly one specific request handle.

AUTHOR

Joshua S. Day (HAX)

LICENSE

Same terms as Perl itself.

cpanm Linux::Event::Fork

perl -MCPAN -e shell
install Linux::Event::Fork