/ 
Acme-Parataxis-v0.1.3
/ Acme::Parataxis::Driver::IOAsync

NAME

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

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

DESCRIPTION

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

Key operational characteristics:

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

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

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

CONSTRUCTOR

new( loop => $loop )

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

Constructs a new driver instance. $loop is required and must be an instance of (or inherit from) IO::Async::Loop.

METHODS

watch_read( $fh, $cb ) / watch_write( $fh, $cb )

Registers a read or write callback on $fh and returns $fh. If both directions are registered on the same handle, they share a single underlying watch_io registration. Croaks if $fh is closed.

unwatch( $fh )

Removes all read and write watchers for $fh on the loop. Returns true if the handle was monitored; false otherwise.

timer( $ms, $cb )

Arms a timer to invoke $cb->() after $ms milliseconds. Returns an opaque timer ID.

cancel_timer( $id )

Cancels an active timer. Returns true if successfully cancelled; false if unknown or already expired.

drive( )

Executes $loop->loop_once(undef), blocking in the kernel until an event fires. Invoked by the scheduler when all fibers are parked.

poll_ready( )

Executes $loop->loop_once(0). Performs an immediate non-blocking poll pass, firing due timers without delaying the caller.

Behavior Notes

  • Idle drive blocks

    Calling drive() manually when no watchers or timers are active will block indefinitely inside loop_once(undef). The Parataxis scheduler prevents this by only calling drive() while $driver->pending is positive.

  • Dual-direction write preference

    When a filehandle is monitored for both read and write readiness, an event loop pass on a connected socket often reports the writable branch first. The scheduler handles this naturally on subsequent passes.

SEE ALSO

Acme::Parataxis, Acme::Parataxis::Driver, Acme::Parataxis::Driver::Mojo, IO::Async::Loop

AUTHOR

Sanko Robinson https://github.com/sanko

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2.