Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Driver - Base Class for Event-Loop Adapters Driving Parataxis

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[await_read await_sleep fiber];
    use Mojo::IOLoop;

    # Attach an event loop. Parataxis wraps it in the matching reference driver:
    Acme::Parataxis->attach_loop( Mojo::IOLoop->new );

    Acme::Parataxis::run( sub {
        my $reader = fiber { await_read( $socket, 2000 ) };    # an I/O watch on the loop
        my $napper = fiber { await_sleep(50) };                # a timer on the loop
        ...
    } );

    Acme::Parataxis->detach_loop;    # unwinds all watches/timers; reverts to C thread pool

=head1 DESCRIPTION

A driver is the adapter between Parataxis and an existing CPAN event loop. Attaching a loop via L<<
Acme::Parataxis->attach_loop|Acme::Parataxis/attach_loop >> switches C<await_read>, C<await_write>, and C<await_sleep>
away from submitting jobs to the background OS worker pool. Instead, readiness and timers are registered directly with
the attached loop.

The immediate benefit is multiplexing via C<epoll>, C<kqueue>, or reactor notification rather than dedicating a C
thread parked in C<select()> per filehandle. This also lifts the traditional C<FD_SETSIZE> ceiling on platforms where
the event loop supports modern poll interfaces.

The division of labor is strictly isolated:

=over

=item *

The B<driver> manages loop registrations: it tells the event loop which handles to watch and which timers to arm, and
hands control to the loop when all fibers are parked.

=item *

The B<scheduler> retains complete ownership of fibers, parks, and resumes. Loop callbacks B<only enqueue fibers> back
onto the run queue; they never execute user code directly. This prevents re-entrancy into the scheduler from inside
third-party event loop ticks.

=item *

Parataxis and the event loop never invoke each other's user callbacks—they cooperate exclusively through readiness
triggers.

=back

From the perspective of a running fiber, the API contract is unchanged: C<await_read> and C<await_write> return C<1> on
readiness, C<-1> on timeout or unwatchable descriptor, and enclosing C<with_timeout> or nursery scopes abort cleanly.

Two reference drivers ship with the distribution: L<Acme::Parataxis::Driver::Mojo> (for C<Mojo::IOLoop> and
C<Mojo::Reactor>) and L<Acme::Parataxis::Driver::IOAsync> (for C<IO::Async::Loop>). L<<



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