Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Compat - Transparent Gevent-Style Cooperative Unblocking of Builtins

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[async fiber];

    # Must be installed at compile time, in a BEGIN block, above affected code:
    BEGIN { Acme::Parataxis->enable_transparent_unblocking() }

    async {
        my $sock = IO::Socket::INET->new( PeerAddr => 'example.com:80' ) or die $!;

        # Standard blocking builtins are now cooperative inside fibers:
        my $napper = fiber {
            sleep 0.05;    # yields to the scheduler; does not block the OS thread
            say 'f1: finished sleep';
        };

        my $reader = fiber {
            my $buf = q{};
            read( $sock, $buf, 64 );    # frames onto await_read; yields while waiting
            say "f2: read ${\length($buf)} bytes";
        };

        $napper->await;
        $reader->await;
    };

=head1 DESCRIPTION

C<Acme::Parataxis::Compat> provides an opt-in, C<gevent>-style compatibility layer for legacy synchronous code. By
installing C<CORE::GLOBAL> overrides for C<sleep>, C<read>, and C<sysread>, existing modules and synchronous loops run
cooperatively inside fibers without freezing the entire process:

=over

=item * C<sleep> becomes L<await_sleep|Acme::Parataxis/await_sleep>

The calling fiber yields for the requested duration while other fibers proceed. Fractional seconds are honored with
millisecond precision (C<sleep 0.05> sleeps 50ms, whereas C<CORE::sleep> truncates this to 0). When called outside a
fiber, it falls back immediately to C<CORE::sleep>. The C<$_> default argument is supported.

=item * C<read> and C<sysread> become non-blocking reads framed on L<await_read|Acme::Parataxis/await_read>

The fiber parks until the filehandle is reported readable, flips the handle non-blocking, reads available bytes, and
restores the original handle mode. B<It can return fewer bytes than requested>, exactly like a non-blocking socket
read; callers needing an exact byte count should loop.

=item * Everything else remains untouched

C<select>, C<alarm>, C<connect>, and C-level extensions like C<DBI> are not intercepted and remain blocking. Use
L<await_read|Acme::Parataxis/await_read>, L<await_write|Acme::Parataxis/await_write>, or L<Acme::Parataxis::Blocking>
for those.

=back



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