Bug #122948 for IO-Async: Documentation improvements

Documenting the tricky bits I came across in ::Stream

From 8f39fe578cb2da515c711b7e8b438dfb3c064cfb Mon Sep 17 00:00:00 2001 From: Yanick Champoux <yanick@babyl.dyndns.org> Date: Sun, 3 Sep 2017 13:35:32 -0400 Subject: [PATCH 1/3] typo --- lib/IO/Async/Stream.pm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/IO/Async/Stream.pm b/lib/IO/Async/Stream.pm index 89123b2..6f03eb9 100644 --- a/lib/IO/Async/Stream.pm +++ b/lib/IO/Async/Stream.pm @@ -327,7 +327,7 @@ be invoked as Each is expected to modify the passed buffer; C<reader> by appending to it, C<writer> by removing a prefix from it. Each is expected to return a true value on success, zero on EOF, or C<undef> with C<$!> set for errors. If not -provided, they will be substituted by implenentations using C<sysread> and +provided, they will be substituted by implementations using C<sysread> and C<syswrite> on the underlying handle, respectively. =head2 close_on_read_eof => BOOL -- 2.9.2

From d20e260e43eb7d59bc5252a4a9b99c46d8bdb047 Mon Sep 17 00:00:00 2001 From: Yanick Champoux <yanick@babyl.dyndns.org> Date: Sun, 3 Sep 2017 13:53:35 -0400 Subject: [PATCH 2/3] provide an example for 'writer' and 'reader' ... as it's not obvious how to modify the $buffer from the description alone. --- lib/IO/Async/Stream.pm | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/lib/IO/Async/Stream.pm b/lib/IO/Async/Stream.pm index 6f03eb9..5c579ce 100644 --- a/lib/IO/Async/Stream.pm +++ b/lib/IO/Async/Stream.pm @@ -326,7 +326,31 @@ be invoked as Each is expected to modify the passed buffer; C<reader> by appending to it, C<writer> by removing a prefix from it. Each is expected to return a true -value on success, zero on EOF, or C<undef> with C<$!> set for errors. If not +value on success, zero on EOF, or C<undef> with C<$!> set for errors. + + my $stream = IO::Async::Stream->new( + ..., + reader => sub { + my( $stream, $read_handle, $buffer, $len ) = @_; + + # important to use $_[2] and not $buffer! + substr $_[2], length $buffer, 0, 'new data...'; + + return 1; + }, + writer => sub { + my( $stream, $write_handle, $buffer, $len ) = @_; + + # important to use $_[2] and not $buffer! + my $data = substr $_[2], 0, $len, ''; + + print "we got ", $data; + + return 1; + }, + ); + +If not provided, they will be substituted by implementations using C<sysread> and C<syswrite> on the underlying handle, respectively. -- 2.9.2

From b2d8650a5f7f5762c1d09c20b1345f83adc6f855 Mon Sep 17 00:00:00 2001 From: Yanick Champoux <yanick@babyl.dyndns.org> Date: Sun, 3 Sep 2017 13:54:30 -0400 Subject: [PATCH 3/3] explain what to do if the write_fh redirect to a scalar --- lib/IO/Async/Stream.pm | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/lib/IO/Async/Stream.pm b/lib/IO/Async/Stream.pm index 5c579ce..34bba9d 100644 --- a/lib/IO/Async/Stream.pm +++ b/lib/IO/Async/Stream.pm @@ -229,6 +229,48 @@ The IO handle to read from. Must implement C<fileno> and C<sysread> methods. The IO handle to write to. Must implement C<fileno> and C<syswrite> methods. +Note that filehandles redirecting to a scalar don't implement C<syswrite>. + + # this works + + open my $fh, '>', 'foo/bar.txt'; + + my $stream = IO::Async::Stream->new( + ..., + write_handle => $fh, + ); + + # this won't! + + open my $fh, '>', \my $output; + + my $stream = IO::Async::Stream->new( + ..., + write_handle => $fh, + ); + +If it's possible that the write filehandle will +redirect to a scalar, use the C<writer> attribute +to override the use of C<syswrite>. + + # this will work + + open my $fh, '>', \my $output; + + my $stream = IO::Async::Stream->new( + ..., + write_handle => $fh, + writer => sub { + my( $stream, $write_handle, $buffer, $len ) = @_; + + # important to use $_[2] and not '$buffer' + $write_handle->write( substr $_[2], 0, $len, '' ); + + return 1; + }, + ); + + =head2 handle => IO Shortcut to specifying the same IO handle for both of the above. -- 2.9.2