PerlIO Layer implementation future proofing.

 - Inspired by Nick C's suggestion add size of function table to the table
   as a validation check.
 - also optimize pseudo-layer code to avoid malloc/link of something
   destined to be immediately popped & freed.
 - Minor addition to pod/perliol.pod

p4raw-id: //depot/perlio@17330

1 files changed, 27 insertions, 10 deletions

diff --git a/pod/perliol.pod b/pod/perliol.pod
index 81cbab17e7..da4abe72cc 100644
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -87,10 +87,11 @@ same as the public C<PerlIO_xxxxx> functions:
 
   struct _PerlIO_funcs
   {
+   Size_t		fsize;
    char *		name;
    Size_t		size;
    IV		kind;
-   IV		(*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg);
+   IV		(*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab);
    IV		(*Popped)(pTHX_ PerlIO *f);
    PerlIO *	(*Open)(pTHX_ PerlIO_funcs *tab,
   			AV *layers, IV n,
@@ -124,9 +125,9 @@ same as the public C<PerlIO_xxxxx> functions:
    void		(*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
   };
 
-The first few members of the struct give a "name" for the layer, the
-size to C<malloc> for the per-instance data, and some flags which are
-attributes of the class as whole (such as whether it is a buffering
+The first few members of the struct give a function table size for
+compatibility check "name" for the layer, the  size to C<malloc> for the per-instance data,
+and some flags which are attributes of the class as whole (such as whether it is a buffering
 layer), then follow the functions which fall into four basic groups:
 
 =over 4
@@ -323,6 +324,14 @@ to change during one "get".)
 
 =over 4
 
+=item size
+
+	Size_t fsize;
+
+Size of the function table. This is compared against the value PerlIO code "knows"
+as a compatibility check. Future versions I<may> be able to tolerate layers
+compiled against an old version of the headers.
+
 =item name
 
 	char * name;
@@ -343,6 +352,14 @@ The size of the per-instance data structure, e.g.:
 
   sizeof(PerlIOAPR)
 
+If this field is zero then C<PerlIO_pushed> does not malloc anything and assumes
+layer's Pushed function will do any required layer stack manipulation - used
+to avoid malloc/free overhead for dummy layers.
+If the field is non-zero it must be at least the size of C<PerlIOl>,
+C<PerlIO_pushed> will allocate memory for the layer's data structures
+and link new layer onto the stream's stack. (If the layer's Pushed
+method returns an error indication the layer is popped again.)
+
 =item kind
 
 	IV kind;
@@ -492,18 +509,18 @@ Returns the Unix/Posix numeric file descriptor for the handle. Normally
 C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
 for this.
 
-Returns -1 if the layer cannot provide such a file descriptor, or in
-the case of the error.
-
-XXX: two possible results end up in -1, one is an error the other is
-not.
+Returns -1 on error, which is considered to include the case where the layer cannot
+provide such a file descriptor.
 
 =item Dup
 
 	PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
 			CLONE_PARAMS *param, int flags);
 
-XXX: not documented
+XXX: Needs more docs.
+
+Used as part of the "clone" process when a thread is spawned (in which case
+param will be non-NULL) and when a stream is being duplicated via '&' in the C<open>.
 
 Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.