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 )