diff options
Diffstat (limited to 'pod/perlguts.pod')
| -rw-r--r-- | pod/perlguts.pod | 137 |
1 files changed, 118 insertions, 19 deletions
diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 2eb5229060..28c196017c 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<av_len> function returns the highest index value in array (just like $#array in Perl). If the array is empty, -1 is returned. The C<av_fetch> function returns the value at index C<key>, but if C<lval> is non-zero, then C<av_fetch> will store an undef value at that index. -The C<av_store> function stores the value C<val> at index C<key>. -note that C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s -as their return value. +The C<av_store> function stores the value C<val> at index C<key>, and does +not increment the reference count of C<val>. Thus the caller is responsible +for taking care of that, and if C<av_store> returns NULL, the caller will +have to decrement the reference count to avoid a memory leak. Note that +C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'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<Understanding the Magic of Tied Hashes and Arrays> 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<PERL_HASH(hash, key, klen)> macro: while (i--) hash = hash * 33 + *s++; +See L<Understanding the Magic of Tied Hashes and Arrays> 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 C<SV*>s: HeKEY(HE* he) HeKLEN(HE* he) +Note that both C<hv_store> and C<hv_store_ent> do not increment the +reference count of the stored C<val>, 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<val> to avoid a memory leak. =head2 References @@ -697,7 +710,7 @@ stored in the C<mg_type> field. The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC> structure. If it is not the same as the C<sv> argument, the reference count of the C<obj> object is incremented. If it is the same, or if -the C<how> argument is "#", or if it is a null pointer, then C<obj> is +the C<how> argument is "#", or if it is a NULL pointer, then C<obj> is merely stored, without the reference count being incremented. There is also a function to add magic to an C<HV>: @@ -813,6 +826,65 @@ This routine checks to see what types of magic C<sv> has. If the mg_type field is an uppercase letter, then the mg_obj is copied to C<nsv>, 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. + +WARNING: As of the 5.004 release, proper usage of the array and hash +access functions requires understanding a few caveats. Some +of these caveats are actually considered bugs in the API, to be fixed +in later releases, and are bracketed with [MAYCHANGE] below. If +you find yourself actually applying such information in this section, be +aware that the behavior may change in the future, umm, without warning. + +The C<av_store> function, when given a tied array argument, merely +copies the magic of the array onto the value to be "stored", using +C<mg_copy>. It may also return NULL, indicating that the value did not +actually need to be stored in the array. [MAYCHANGE] After a call to +C<av_store> on a tied array, the caller will usually need to call +C<mg_set(val)> to actually invoke the perl level "STORE" method on the +TIEARRAY object. If C<av_store> did return NULL, a call to +C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory +leak. [/MAYCHANGE] + +The previous paragraph is applicable verbatim to tied hash access using the +C<hv_store> and C<hv_store_ent> functions as well. + +C<av_fetch> and the corresponding hash functions C<hv_fetch> and +C<hv_fetch_ent> actually return an undefined mortal value whose magic +has been initialized using C<mg_copy>. Note the value so returned does not +need to be deallocated, as it is already mortal. [MAYCHANGE] But you will +need to call C<mg_get()> 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<mg_set()> on the return value after possibly assigning +a suitable value to it using C<sv_setsv>, which will invoke the "STORE" +method on the TIE object. [/MAYCHANGE] + +[MAYCHANGE] +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<mg_copy> to attach magic to the values that were meant to be +"stored" or "fetched". Later calls to C<mg_get> and C<mg_set> actually +do the job of invoking the TIE methods on the underlying objects. Thus +the magic mechanism currently 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. The API may be +changed to provide more transparent access to both tied and normal data +types in future versions. +[/MAYCHANGE] + +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 +1263,9 @@ Returns the SV at the specified index in the array. The C<key> is the index. If C<lval> 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<SV*>. +See L<Understanding the Magic of Tied Hashes and Arrays> 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 +1305,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<key>. The -return value will be null if the operation failed, otherwise it can be -dereferenced to get the original C<SV*>. +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<SV*>. Note that the +caller is responsible for suitably incrementing the reference count of C<val> +before the call, and decrementing it if the function returned NULL. + +See L<Understanding the Magic of Tied Hashes and Arrays> for more +information on how to use this function on tied arrays. SV** av_store _((AV* ar, I32 key, SV* val)); @@ -1544,7 +1625,7 @@ and C<hv_free_ent>. Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The C<klen> is the length of the key. The -C<flags> value will normally be zero; if set to G_DISCARD then null will be +C<flags> 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 +1634,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<flags> value will normally be zero; if set -to G_DISCARD then null will be returned. C<hash> can be a valid precomputed +to G_DISCARD then NULL will be returned. C<hash> 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 +1660,9 @@ C<klen> is the length of the key. If C<lval> 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<SV*>. +See L<Understanding the Magic of Tied Hashes and Arrays> 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 +1675,9 @@ before accessing it. The return value when C<tb> 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<Understanding the Magic of Tied Hashes and Arrays> 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 +1745,14 @@ Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>. Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is the length of the key. The C<hash> 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<SV*>. +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<SV*>. Note that the caller is +responsible for suitably incrementing the reference count of C<val> +before the call, and decrementing it if the function returned NULL. + +See L<Understanding the Magic of Tied Hashes and Arrays> 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 +1761,15 @@ original C<SV*>. Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash> 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<He???> 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<He???> macros +described here. Note that the caller is responsible for suitably +incrementing the reference count of C<val> before the call, and decrementing +it if the function returned NULL. + +See L<Understanding the Magic of Tied Hashes and Arrays> 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 +2080,7 @@ Releases a Perl interpreter. See L<perlembed>. Returns the AV of the specified Perl array. If C<create> is set and the Perl variable does not exist then it will be created. If C<create> 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 +2088,7 @@ set and the variable does not exist then null is returned. Returns the CV of the specified Perl sub. If C<create> is set and the Perl variable does not exist then it will be created. If C<create> 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 +2096,7 @@ set and the variable does not exist then null is returned. Returns the HV of the specified Perl hash. If C<create> is set and the Perl variable does not exist then it will be created. If C<create> 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 +2104,7 @@ set and the variable does not exist then null is returned. Returns the SV of the specified Perl scalar. If C<create> is set and the Perl variable does not exist then it will be created. If C<create> 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 +3056,4 @@ API Listing by Dean Roehrich <F<roehrich@cray.com>>. =head1 DATE -Version 31.7: 1997/5/1 +Version 31.8: 1997/5/17 |