Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=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

Nothing is modified unless you explicitly invoke C<enable_transparent_unblocking()>, and only code I<compiled after>
the call is affected. Perl resolves C<CORE::GLOBAL> overrides at parse time, so installation must take place within a
C<BEGIN> block placed above the target code. Outside of a running fiber, all three overrides delegate directly to the
native C<CORE::> builtins.

=head1 METHODS

=head2 C<< Acme::Parataxis->enable_transparent_unblocking( ) >>

    BEGIN { Acme::Parataxis->enable_transparent_unblocking() }
    # or:
    BEGIN { Acme::Parataxis::Compat->install() }

Installs the C<CORE::GLOBAL> overrides and returns C<1>. Idempotent.

=head2 C<< Acme::Parataxis->disable_transparent_unblocking( ) >>

    Acme::Parataxis->disable_transparent_unblocking();
    # or:
    Acme::Parataxis::Compat->disable();

Restores the global symbols to their pre-installation state. Safely clears internal subroutine depth tracking so Perl's
subroutine finalization does not trigger "Can't undef active subroutine" errors. Only code compiled I<after> this call
reverts to the builtins.

=head2 C<< Acme::Parataxis->transparent_unblocking( ) >>

    say 'Active' if Acme::Parataxis->transparent_unblocking();
    # or:
    say 'Active' if Acme::Parataxis::Compat->installed();

Returns true if the transparent unblocking overrides are currently installed.

=head1 Recipes

=head2 Enabling unblocking for a single file or script

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

    BEGIN { Acme::Parataxis->enable_transparent_unblocking() }

    use Net::FTP;    # compiled AFTER the overrides; its internal reads and sleeps cooperate!

    async {
        my $ftp = fiber { Net::FTP->new('ftp.example.com', Timeout => 10) };
        $ftp->await;
    };

=head2 Reading an exact number of bytes safely

Because non-blocking reads return as soon as data arrives, wrap reads in a loop when a fixed payload size is required:

    sub read_exact ( $fh, $len ) {
        my $buf = q{};
        my $got = 0;
        while ( $got < $len ) {
            my $n = read( $fh, $buf, $len - $got, $got );
            last if !defined($n) || $n == 0;    # error or EOF
            $got += $n;
        }
        return $buf;
    }

The C<OFFSET> parameter places each chunk at the correct offset in the buffer without extra string copies.

=head2 Scoped testing and cleanup

    use Test2::V1;
    use Acme::Parataxis;

    subtest 'sleep restores truncation outside overrides' => sub {
        Acme::Parataxis->disable_transparent_unblocking();
        my $rc = eval 'sleep(0.05)';    # eval forces compilation after disable()
        is $rc, 0, 'raw CORE::sleep truncated fractional seconds';
        Acme::Parataxis->enable_transparent_unblocking();
    };

=head1 Behavior Notes

=over

=item * Short reads are normal

Perl's builtin C<read()> blocks the entire OS thread until the requested buffer is completely filled. C<Compat::read>
cannot do this without freezing sibling fibers. Instead, it waits for readiness and returns whatever bytes have
arrived. Always loop if your protocol requires a fixed frame length.

=item * Waiting remains fully cancellable

Waiting for a handle to become readable parks the fiber in the scheduler. Deadlines from
L<with_timeout|Acme::Parataxis/with_timeout>, cancellations from L<Acme::Parataxis::CancellationToken>, and nursery
abort signals will interrupt the wait cleanly.

=item * Original handle modes are restored

The override switches the filehandle to non-blocking mode (via C<< IO::Handle::blocking($fh, 0) >>) only for the
duration of the read, and restores the original mode before returning. Code compiled before installation that shares
the handle continues to observe standard blocking semantics.

=item * Bareword filehandles stop compiling

Because C<CORE::GLOBAL> overrides cannot reproduce the compiler's specialized grammar rules for bareword filehandles,
code compiled under C<use strict> after installation will fail to compile bareword handles:

    BEGIN { Acme::Parataxis->enable_transparent_unblocking() }



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