Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Driver::IOAsync - IO::Async Event Loop Driver for Parataxis

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[await_read await_sleep fiber];
    use IO::Async::Loop;

    # Wrap an IO::Async loop and make it the active driver:
    Acme::Parataxis->attach_loop( IO::Async::Loop->new );

    Acme::Parataxis::run( sub {
        my $sender = fiber {
            await_sleep(30);
            syswrite( $socket, "ping\n" );
        };

        # I/O readiness driven by IO::Async (epoll/select):
        await_read( $socket, 2000 );
    } );

    Acme::Parataxis->detach_loop;    # reverts to built-in native thread pool

=head1 DESCRIPTION

C<Acme::Parataxis::Driver::IOAsync> connects Parataxis to an L<IO::Async::Loop>. When attached, calls to C<await_read>,
C<await_write>, and C<await_sleep> register filehandle watchers and timers directly with the C<IO::Async> loop rather
than delegating to the native C thread pool.

Key operational characteristics:

=over

=item *

B<Loop abstraction>: C<< IO::Async::Loop->new >> detects and instantiates the best backend available for your platform
(such as C<IO::Async::Loop::Epoll> on Linux or C<IO::Async::Loop::Select> on Windows). The driver interacts strictly
via the documented C<watch_io>, C<unwatch_io>, and C<watch_time> methods.

=item *

B<Truly non-blocking polling>: C<poll_ready()> maps directly to C<< $loop->loop_once(0) >>, returning instantly while
still firing due timers. This prevents polling stalls when coordinating with background workers.

=item *

B<Automatic non-blocking handles>: C<IO::Async> configures C<O_NONBLOCK> automatically when a handle is first monitored
with C<watch_io>.

=back

=head1 CONSTRUCTOR

=head2 C<new( loop =E<gt> $loop )>

    my $driver = Acme::Parataxis::Driver::IOAsync->new( loop => $loop );



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