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 )