From: Gurusamy Sarathy Date: Wed, 30 Apr 1997 22:14:34 +0000 (+1200) Subject: perlguts caveats X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=04343c6db20ad44e9b9b5531ea62e7099311ed51;p=p5sagit%2Fp5-mst-13.2.git perlguts caveats Subject: perlguts additions Here are some additions that describe tied hash and array access. p5p-msgid: 199705180052.UAA22066@aatma.engin.umich.edu Signed-off-by: Ilya Zakharevich --- diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 2eb5229..33b5120 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -161,7 +161,7 @@ Take this code: sv_setsv(ST(0), sv); This code tries to return a new SV (which contains the value 42) if it should -return a real value, or undef otherwise. Instead it has returned a null +return a real value, or undef otherwise. Instead it has returned a NULL pointer which, somewhere down the line, will cause a segmentation violation, bus error, or just weird results. Change the zero to C<&sv_undef> in the first line and all will be well. @@ -225,9 +225,12 @@ The C function returns the highest index value in array (just like $#array in Perl). If the array is empty, -1 is returned. The C function returns the value at index C, but if C is non-zero, then C will store an undef value at that index. -The C function stores the value C at index C. -note that C and C both return C's, not C's -as their return value. +The C function stores the value C at index C, and does +not increment the reference count of C. Thus the caller is responsible +for taking care of that, and if C returns NULL, the caller will +have to decrement the reference count to avoid a memory leak. Note that +C and C both return C's, not C's as their +return value. void av_clear(AV*); void av_undef(AV*); @@ -247,6 +250,9 @@ by using the following: This returns NULL if the variable does not exist. +See L for more +information on how to use the array access functions on tied arrays. + =head2 Working with HVs To create an HV, you use the following routine: @@ -327,6 +333,9 @@ The hash algorithm is defined in the C macro: while (i--) hash = hash * 33 + *s++; +See L for more +information on how to use the hash access functions on tied hashes. + =head2 Hash API Extensions Beginning with version 5.004, the following functions are also supported: @@ -368,6 +377,10 @@ dealing with keys that are not Cs: HeKEY(HE* he) HeKLEN(HE* he) +Note that both C and C do not increment the +reference count of the stored C, which is the caller's responsibility. +If these functions return a NULL value, the caller will usually have to +decrement the reference count of C to avoid a memory leak. =head2 References @@ -697,7 +710,7 @@ stored in the C field. The C argument is stored in the C field of the C structure. If it is not the same as the C argument, the reference count of the C object is incremented. If it is the same, or if -the C argument is "#", or if it is a null pointer, then C is +the C argument is "#", or if it is a NULL pointer, then C is merely stored, without the reference count being incremented. There is also a function to add magic to an C: @@ -813,6 +826,57 @@ This routine checks to see what types of magic C has. If the mg_type field is an uppercase letter, then the mg_obj is copied to C, but the mg_type field is changed to be the lowercase letter. +=head2 Understanding the Magic of Tied Hashes and Arrays + +Tied hashes and arrays are magical beasts of the 'P' magic type. +Proper usage of the array and hash access functions on them requires +understanding a few caveats. + +The C function, when given a tied array argument, merely +copies the magic of the array onto the value to be "stored", using +C. It may also return NULL, indicating that the value did not +actually need to be stored in the array. After a call to C on +a tied array, the caller will usually need to call C to +actually invoke the perl level "STORE" method on the TIEARRAY object. If +C did return NULL, a call to C will also be +usually necessary to avoid a memory leak. + +The previous paragraph is applicable verbatim to tied hash access using the +C and C functions as well. + +C and the corresponding hash functions C and +C actually return an undefined mortal value whose magic +has been initialized using C. Note the value so returned does not +need to be deallocated, as it is already mortal. But you will need to +call C on the returned value in order to actually invoke the +perl level "FETCH" method on the underlying TIE object. Similarly, +you may also call C on the return value after possibly assigning +a suitable value to it using C, which will invoke the "STORE" +method on the TIE object. + +In other words, the array or hash fetch/store functions don't really +fetch and store actual values in the case of tied arrays and hashes. They +merely call C to attach magic to the values that were meant to be +"stored" or "fetched". Later calls to C and C actually +do the job of invoking the TIE methods on the underlying objects. Thus +the magic mechanism actually implements a kind of lazy access to arrays +and hashes. + +Currently (as of perl version 5.004), use of the hash and array access +functions requires the user to be aware of whether they are operating on +"normal" hashes and arrays, or on their tied variants. A simpler API +interface that provides transparent access to both tied and normal data +types may be available in future versions. + +You would do well to understand that the TIEARRAY and TIEHASH interfaces +are mere sugar to invoke some perl method calls while using the uniform hash +and array syntax. The use of this sugar imposes some overhead (typically +about two to four extra opcodes per FETCH/STORE operation, in addition to +the creation of all the mortal variables required to invoke the methods). +This overhead will be comparatively small if the TIE methods are themselves +substantial, but if they are only a few statements long, the overhead +will not be insignificant. + =head1 Subroutines =head2 XSUBs and the Argument Stack @@ -1191,6 +1255,9 @@ Returns the SV at the specified index in the array. The C is the index. If C is set then the fetch will be part of a store. Check that the return value is non-null before dereferencing it to a C. +See L for more +information on how to use this function on tied arrays. + SV** av_fetch _((AV* ar, I32 key, I32 lval)); =item av_len @@ -1230,8 +1297,14 @@ Shifts an SV off the beginning of the array. =item av_store Stores an SV in an array. The array index is specified as C. The -return value will be null if the operation failed, otherwise it can be -dereferenced to get the original C. +return value will be NULL if the operation failed or if the value did not +need to be actually stored within the array (as in the case of tied arrays). +Otherwise it can be dereferenced to get the original C. Note that the +caller is responsible for suitably incrementing the reference count of C +before the call, and decrementing it if the function returned NULL. + +See L for more +information on how to use this function on tied arrays. SV** av_store _((AV* ar, I32 key, SV* val)); @@ -1544,7 +1617,7 @@ and C. Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The C is the length of the key. The -C value will normally be zero; if set to G_DISCARD then null will be +C value will normally be zero; if set to G_DISCARD then NULL will be returned. SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags)); @@ -1553,7 +1626,7 @@ returned. Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The C value will normally be zero; if set -to G_DISCARD then null will be returned. C can be a valid precomputed +to G_DISCARD then NULL will be returned. C can be a valid precomputed hash value, or 0 to ask for it to be computed. SV* hv_delete_ent _((HV* tb, SV* key, I32 flags, U32 hash)); @@ -1579,6 +1652,9 @@ C is the length of the key. If C is set then the fetch will be part of a store. Check that the return value is non-null before dereferencing it to a C. +See L for more +information on how to use this function on tied hashes. + SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval)); =item hv_fetch_ent @@ -1591,6 +1667,9 @@ before accessing it. The return value when C is a tied hash is a pointer to a static location, so be sure to make a copy of the structure if you need to store it somewhere. +See L for more +information on how to use this function on tied hashes. + HE* hv_fetch_ent _((HV* tb, SV* key, I32 lval, U32 hash)); =item hv_free_ent @@ -1658,8 +1737,14 @@ Returns the package name of a stash. See C, C. Stores an SV in a hash. The hash key is specified as C and C is the length of the key. The C parameter is the precomputed hash value; if it is zero then Perl will compute it. The return value will be -null if the operation failed, otherwise it can be dereferenced to get the -original C. +NULL if the operation failed or if the value did not need to be actually +stored within the hash (as in the case of tied hashes). Otherwise it can +be dereferenced to get the original C. Note that the caller is +responsible for suitably incrementing the reference count of C +before the call, and decrementing it if the function returned NULL. + +See L for more +information on how to use this function on tied hashes. SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash)); @@ -1668,9 +1753,15 @@ original C. Stores C in a hash. The hash key is specified as C. The C parameter is the precomputed hash value; if it is zero then Perl will compute it. The return value is the new hash entry so created. It will be -null if the operation failed or if the entry was stored in a tied hash. -Otherwise the contents of the return value can be accessed using the -C macros described here. +NULL if the operation failed or if the value did not need to be actually +stored within the hash (as in the case of tied hashes). Otherwise the +contents of the return value can be accessed using the C macros +described here. Note that the caller is responsible for suitably +incrementing the reference count of C before the call, and decrementing +it if the function returned NULL. + +See L for more +information on how to use this function on tied hashes. HE* hv_store_ent _((HV* tb, SV* key, SV* val, U32 hash)); @@ -1981,7 +2072,7 @@ Releases a Perl interpreter. See L. Returns the AV of the specified Perl array. If C is set and the Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then null is returned. +set and the variable does not exist then NULL is returned. AV* perl_get_av _((char* name, I32 create)); @@ -1989,7 +2080,7 @@ set and the variable does not exist then null is returned. Returns the CV of the specified Perl sub. If C is set and the Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then null is returned. +set and the variable does not exist then NULL is returned. CV* perl_get_cv _((char* name, I32 create)); @@ -1997,7 +2088,7 @@ set and the variable does not exist then null is returned. Returns the HV of the specified Perl hash. If C is set and the Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then null is returned. +set and the variable does not exist then NULL is returned. HV* perl_get_hv _((char* name, I32 create)); @@ -2005,7 +2096,7 @@ set and the variable does not exist then null is returned. Returns the SV of the specified Perl scalar. If C is set and the Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then null is returned. +set and the variable does not exist then NULL is returned. SV* perl_get_sv _((char* name, I32 create)); @@ -2957,4 +3048,4 @@ API Listing by Dean Roehrich >. =head1 DATE -Version 31.7: 1997/5/1 +Version 31.8: 1997/5/17