RE: [PATCH] Pod::InputObjects performance de-pessimization

[p5sagit/p5-mst-13.2.git] / pod / perliol.pod

diff --git a/pod/perliol.pod b/pod/perliol.pod
index 08ea7c6..9abc72e 100644 (file)
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -420,7 +420,10 @@ struct.  It should also C<Unread()> any unconsumed data that has been
 read and buffered from the layer below back to that layer, so that it
 can be re-provided to what ever is now above.
 
-Returns 0 on success and failure.
+Returns 0 on success and failure.  If C<Popped()> returns I<true> then
+I<perlio.c> assumes that either the layer has popped itself, or the
+layer is super special and needs to be retained for other reasons.
+In most cases it should return I<false>.
 
 =item Open
 
@@ -478,6 +481,10 @@ and wait to be "pushed".  If a layer does provide C<Open()> it should
 normally call the C<Open()> method of next layer down (if any) and
 then push itself on top if that succeeds.
 
+If C<PerlIO_push> was performed and open has failed, it must
+C<PerlIO_pop> itself, since if it's not, the layer won't be removed
+and may cause bad problems.
+
 Returns C<NULL> on failure.
 
 =item Binmode
@@ -675,6 +682,68 @@ The application (or layer above) must ensure they are consistent.
 
 =back
 
+=head2 Implementing PerlIO Layers
+
+If you find the implementation document unclear or not sufficient,
+look at the existing perlio layer implementations, which include:
+
+=over
+
+=item * C implementations
+
+PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.
+
+PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN.
+
+=item * Perl implementations
+
+PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN.
+
+=back
+
+If you are creating a PerlIO layer, you may want to be lazy, in other
+words, implement only the methods that interest you.  The other methods
+you can either replace with the "blank" methods
+
+    PerlIOBase_noop_ok
+    PerlIOBase_noop_fail
+
+(which do nothing, and return zero and -1, respectively) or for
+certain methods you may assume a default behaviour by using a NULL
+method.  The Open method looks for help in the 'parent' layer.
+The following table summarizes the behaviour:
+
+    method      behaviour with NULL
+
+    Clearerr    PerlIOBase_clearerr
+    Close       PerlIOBase_close
+    Dup         PerlIOBase_dup
+    Eof         PerlIOBase_eof
+    Error       PerlIOBase_error
+    Fileno      PerlIOBase_fileno
+    Fill        FAILURE
+    Flush       SUCCESS
+    Getarg      SUCCESS
+    Get_base    FAILURE
+    Get_bufsiz  FAILURE
+    Get_cnt     FAILURE
+    Get_ptr     FAILURE
+    Open        INHERITED
+    Popped      SUCCESS
+    Pushed      SUCCESS
+    Read        PerlIOBase_read
+    Seek        FAILURE
+    Set_cnt     FAILURE
+    Set_ptrcnt  FAILURE
+    Setlinebuf  PerlIOBase_setlinebuf
+    Tell        FAILURE
+    Unread      PerlIOBase_unread
+    Write       FAILURE
+
+ FAILURE        Set errno (to EINVAL in UNIXish, to LIB$_INVARG in VMS) and
+                return -1 (for numeric return values) or NULL (for pointers)
+ INHERITED      Inherited from the layer below
+ SUCCESS        Return 0 (for numeric return values) or a pointer 
 
 =head2 Core Layers
 
@@ -782,23 +851,27 @@ called thus:
 
    open( $fh, "<:encoding(iso-8859-7)", $pathname );
 
-=item ":Scalar"
+=item ":scalar"
 
 Provides support for reading data from and writing data to a scalar.
 
-   open( $fh, ":Scalar", \$scalar );
+   open( $fh, "+<:scalar", \$scalar );
 
 When a handle is so opened, then reads get bytes from the string value
 of I<$scalar>, and writes change the value. In both cases the position
 in I<$scalar> starts as zero but can be altered via C<seek>, and
 determined via C<tell>.
 
-=item ":Via"
+Please note that this layer is implied when calling open() thus:
+
+   open( $fh, "+<", \$scalar );
+
+=item ":via"
 
 Provided to allow layers to be implemented as Perl code.  For instance:
 
    use PerlIO::via::StripHTML;
-   open( my $fh, ">:Via(StripHTML)", "index.html" );
+   open( my $fh, "<:via(StripHTML)", "index.html" );
 
 See L<PerlIO::via> for details.