Acme-Parataxis

 view release on metacpan or  search on metacpan

lib/Acme/Parataxis.pod  view on Meta::CPAN

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis - Lightweight Cooperative Fibers

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[:all];
    $|++;
    async {
        say 'Main task started';
        my $f1 = fiber {
            say '  Task 1: Sleeping...';
            await_sleep(1000);
            say '  Task 1: Waking up';
            return 'Coffee!';
        };
        my $f2 = fiber {
            say '  Task 2: Calculating... (simulated CPU work)';
            my $sum = 0;
            for ( 1 .. 100 ) {
                $sum += $_;
                yield;    # yield control back to the scheduler
            }
            say '  Task 2: Complete. Will return ' . $sum;
            return $sum;
        };

        # await works on fibers and futures
        say 'Result 1: ' . await($f1);
        say 'Result 2: ' . await($f2);
    };
    # Output:
    # Main task started
    #   Task 1: Sleeping...
    #   Task 2: Calculating... (simulated CPU work)
    #   Task 2: Complete. Will return 5050
    #   Task 1: Waking up
    # Result 1: Coffee!
    # Result 2: 5050

=head1 DESCRIPTION

C<Acme::Parataxis> brings stackful cooperative multitasking (green threads or fibers) and native thread-pool offloading
to Perl. It combines cooperative multitasking (fibers) with a preemptive native thread pool.

All Perl code runs within a fiber: a user-space thread of execution with its own C-level execution context and
independent Perl interpreter stacks (argument, mark, scope, save, and mortal stacks). Unlike preemptive OS threads,
fibers are cooperatively scheduled: a fiber runs until it yields or pauses for a blocking operation. Because scheduling
is deterministic, mutable state shared across fibers requires no mutex locks unless an operation suspends across a
yield boundary.

When a fiber encounters a blocking task such as sleeping or waiting on a file descriptor, it will not stall the Perl
interpreter. Instead, the calling fiber is suspended, the blocking wait is offloaded to a background OS worker thread
in a native C thread pool (or an attached event loop), and the scheduler resumes other runnable fibers. Once the
background operation completes, the parked fiber is re-enqueued and resumes with its result.

The core exports the scheduler interface (C<async>, C<run>), fiber lifecycle tools (C<fiber>, C<spawn>, C<yield>,
C<await>), async I/O primitives (C<await_sleep>, C<await_read>, C<await_write>), structured concurrency (C<nursery>),



( run in 0.390 second using v1.01-cache-2.11-cpan-234fa220139 )