view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis - Perl Coroutines Using Real OS Fibers via FFI

=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);
            return 'Coffee!';
        };

        my $f2 = fiber {
            say '  Task 2: Calculating... (simulated CPU work)';
            my $sum = 0;
            for ( 1 .. 100 ) {
                $sum += $_;
                maybe_yield();    # Be a good neighbor
            }
            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);
    };

=head1 DESCRIPTION

C<Acme::Parataxis> implements a hybrid concurrency model for Perl, greatly inspired by the concurrency system for the
L<Wren|https://wren.io/concurrency.html> programming language. It combines cooperative multitasking (fibers) with a
preemptive native thread pool.

Fibers are modern hardware's mechanism for lightweight concurrency. They are similar to threads but are cooperatively
scheduled. While the OS may switch between threads at any time, a fiber only passes control when explicitly told to do
so. This makes concurrency deterministic and easier to reason about. You (probably) don't have to worry about random
context switches clobbering your data. Each fiber has its own stack and context, but they don't use OS thread
resources. You can easily create thousands of them without stalling your system.

While this module lives in the C<Acme::> namespace due to its highly experimental origins (it manually manipulates
Perl's internal stacks and C context via FFI), it is designed to be a robust and highly functional concurrency
framework.

=head1 Core Concepts

=head2 Creating Fibers

All Perl code in this system runs within a fiber. When you start your script or call C<Acme::Parataxis::run>, a "main"
fiber is active. You can create new fibers using C<spawn> or by manually instantiating an C<Acme::Parataxis> object:

    my $fiber = Acme::Parataxis->new(code => sub {