1Hash::Util::FieldHash(3pPme)rl Programmers Reference GuiHdaesh::Util::FieldHash(3pm)
2
3
4

NAME

6       Hash::Util::FieldHash - Support for Inside-Out Classes
7

SYNOPSIS

9         ### Create fieldhashes
10         use Hash::Util qw(fieldhash fieldhashes);
11
12         # Create a single field hash
13         fieldhash my %foo;
14
15         # Create three at once...
16         fieldhashes \ my(%foo, %bar, %baz);
17         # ...or any number
18         fieldhashes @hashrefs;
19
20         ### Create an idhash and register it for garbage collection
21         use Hash::Util::FieldHash qw(idhash register);
22         idhash my %name;
23         my $object = \ do { my $o };
24         # register the idhash for garbage collection with $object
25         register($object, \ %name);
26         # the following entry will be deleted when $object goes out of scope
27         $name{$object} = 'John Doe';
28
29         ### Register an ordinary hash for garbage collection
30         use Hash::Util::FieldHash qw(id register);
31         my %name;
32         my $object = \ do { my $o };
33         # register the hash %name for garbage collection of $object's id
34         register $object, \ %name;
35         # the following entry will be deleted when $object goes out of scope
36         $name{id $object} = 'John Doe';
37

FUNCTIONS

39       "Hash::Util::FieldHash" offers a number of functions in support of "The
40       Inside-out Technique" of class construction.
41
42       id
43               id($obj)
44
45           Returns the reference address of a reference $obj.  If $obj is not
46           a reference, returns $obj.
47
48           This function is a stand-in replacement for Scalar::Util::refaddr,
49           that is, it returns the reference address of its argument as a
50           numeric value.  The only difference is that "refaddr()" returns
51           "undef" when given a non-reference while "id()" returns its
52           argument unchanged.
53
54           "id()" also uses a caching technique that makes it faster when the
55           id of an object is requested often, but slower if it is needed only
56           once or twice.
57
58       id_2obj
59               $obj = id_2obj($id)
60
61           If $id is the id of a registered object (see "register"), returns
62           the object, otherwise an undefined value.  For registered objects
63           this is the inverse function of "id()".
64
65       register
66               register($obj)
67               register($obj, @hashrefs)
68
69           In the first form, registers an object to work with for the
70           function "id_2obj()".  In the second form, it additionally marks
71           the given hashrefs down for garbage collection.  This means that
72           when the object goes out of scope, any entries in the given hashes
73           under the key of "id($obj)" will be deleted from the hashes.
74
75           It is a fatal error to register a non-reference $obj.  Any non-
76           hashrefs among the following arguments are silently ignored.
77
78           It is not an error to register the same object multiple times with
79           varying sets of hashrefs.  Any hashrefs that are not registered yet
80           will be added, others ignored.
81
82           Registry also implies thread support.  When a new thread is
83           created, all references are replaced with new ones, including all
84           objects.  If a hash uses the reference address of an object as a
85           key, that connection would be broken.  With a registered object,
86           its id will be updated in all hashes registered with it.
87
88       idhash
89               idhash my %hash
90
91           Makes an idhash from the argument, which must be a hash.
92
93           An idhash works like a normal hash, except that it stringifies a
94           reference used as a key differently.  A reference is stringified as
95           if the "id()" function had been invoked on it, that is, its
96           reference address in decimal is used as the key.
97
98       idhashes
99               idhashes \ my(%hash, %gnash, %trash)
100               idhashes \ @hashrefs
101
102           Creates many idhashes from its hashref arguments.  Returns those
103           arguments that could be converted or their number in scalar
104           context.
105
106       fieldhash
107               fieldhash %hash;
108
109           Creates a single fieldhash.  The argument must be a hash.  Returns
110           a reference to the given hash if successful, otherwise nothing.
111
112           A fieldhash is, in short, an idhash with auto-registry.  When an
113           object (or, indeed, any reference) is used as a fieldhash key, the
114           fieldhash is automatically registered for garbage collection with
115           the object, as if "register $obj, \ %fieldhash" had been called.
116
117       fieldhashes
118               fieldhashes @hashrefs;
119
120           Creates any number of field hashes.  Arguments must be hash
121           references.  Returns the converted hashrefs in list context, their
122           number in scalar context.
123

DESCRIPTION

125       A word on terminology:  I shall use the term field for a scalar piece
126       of data that a class associates with an object.  Other terms that have
127       been used for this concept are "object variable", "(object) property",
128       "(object) attribute" and more.  Especially "attribute" has some
129       currency among Perl programmer, but that clashes with the "attributes"
130       pragma.  The term "field" also has some currency in this sense and
131       doesn't seem to conflict with other Perl terminology.
132
133       In Perl, an object is a blessed reference.  The standard way of
134       associating data with an object is to store the data inside the
135       object's body, that is, the piece of data pointed to by the reference.
136
137       In consequence, if two or more classes want to access an object they
138       must agree on the type of reference and also on the organization of
139       data within the object body.  Failure to agree on the type results in
140       immediate death when the wrong method tries to access an object.
141       Failure to agree on data organization may lead to one class trampling
142       over the data of another.
143
144       This object model leads to a tight coupling between subclasses.  If one
145       class wants to inherit from another (and both classes access object
146       data), the classes must agree about implementation details.
147       Inheritance can only be used among classes that are maintained
148       together, in a single source or not.
149
150       In particular, it is not possible to write general-purpose classes in
151       this technique, classes that can advertise themselves as "Put me on
152       your @ISA list and use my methods".  If the other class has different
153       ideas about how the object body is used, there is trouble.
154
155       For reference "Name_hash" in "Example 1" shows the standard
156       implementation of a simple class "Name" in the well-known hash based
157       way.  It also demonstrates the predictable failure to construct a
158       common subclass "NamedFile" of "Name" and the class "IO::File" (whose
159       objects must be globrefs).
160
161       Thus, techniques are of interest that store object data not in the
162       object body but some other place.
163
164   The Inside-out Technique
165       With inside-out classes, each class declares a (typically lexical) hash
166       for each field it wants to use.  The reference address of an object is
167       used as the hash key.  By definition, the reference address is unique
168       to each object so this guarantees a place for each field that is
169       private to the class and unique to each object.  See "Name_id" in
170       "Example 1" for a simple example.
171
172       In comparison to the standard implementation where the object is a hash
173       and the fields correspond to hash keys, here the fields correspond to
174       hashes, and the object determines the hash key.  Thus the hashes appear
175       to be turned inside out.
176
177       The body of an object is never examined by an inside-out class, only
178       its reference address is used.  This allows for the body of an actual
179       object to be anything at all while the object methods of the class
180       still work as designed.  This is a key feature of inside-out classes.
181
182   Problems of Inside-out
183       Inside-out classes give us freedom of inheritance, but as usual there
184       is a price.
185
186       Most obviously, there is the necessity of retrieving the reference
187       address of an object for each data access.  It's a minor inconvenience,
188       but it does clutter the code.
189
190       More important (and less obvious) is the necessity of garbage
191       collection.  When a normal object dies, anything stored in the object
192       body is garbage-collected by perl.  With inside-out objects, Perl knows
193       nothing about the data stored in field hashes by a class, but these
194       must be deleted when the object goes out of scope.  Thus the class must
195       provide a "DESTROY" method to take care of that.
196
197       In the presence of multiple classes it can be non-trivial to make sure
198       that every relevant destructor is called for every object.  Perl calls
199       the first one it finds on the inheritance tree (if any) and that's it.
200
201       A related issue is thread-safety.  When a new thread is created, the
202       Perl interpreter is cloned, which implies that all reference addresses
203       in use will be replaced with new ones.  Thus, if a class tries to
204       access a field of a cloned object its (cloned) data will still be
205       stored under the now invalid reference address of the original in the
206       parent thread.  A general "CLONE" method must be provided to re-
207       establish the association.
208
209   Solutions
210       "Hash::Util::FieldHash" addresses these issues on several levels.
211
212       The "id()" function is provided in addition to the existing
213       "Scalar::Util::refaddr()".  Besides its short name it can be a little
214       faster under some circumstances (and a bit slower under others).
215       Benchmark if it matters.  The working of "id()" also allows the use of
216       the class name as a generic object as described further down.
217
218       The "id()" function is incorporated in id hashes in the sense that it
219       is called automatically on every key that is used with the hash.  No
220       explicit call is necessary.
221
222       The problems of garbage collection and thread safety are both addressed
223       by the function "register()".  It registers an object together with any
224       number of hashes.  Registry means that when the object dies, an entry
225       in any of the hashes under the reference address of this object will be
226       deleted.  This guarantees garbage collection in these hashes.  It also
227       means that on thread cloning the object's entries in registered hashes
228       will be replaced with updated entries whose key is the cloned object's
229       reference address.  Thus the object-data association becomes thread-
230       safe.
231
232       Object registry is best done when the object is initialized for use
233       with a class.  That way, garbage collection and thread safety are
234       established for every object and every field that is initialized.
235
236       Finally, field hashes incorporate all these functions in one package.
237       Besides automatically calling the "id()" function on every object used
238       as a key, the object is registered with the field hash on first use.
239       Classes based on field hashes are fully garbage-collected and thread
240       safe without further measures.
241
242   More Problems
243       Another problem that occurs with inside-out classes is serialization.
244       Since the object data is not in its usual place, standard routines like
245       "Storable::freeze()", "Storable::thaw()" and "Data::Dumper::Dumper()"
246       can't deal with it on their own.  Both "Data::Dumper" and "Storable"
247       provide the necessary hooks to make things work, but the functions or
248       methods used by the hooks must be provided by each inside-out class.
249
250       A general solution to the serialization problem would require another
251       level of registry, one that associates classes and fields.  So far, the
252       functions of "Hash::Util::FieldHash" are unaware of any classes, which
253       I consider a feature.  Therefore "Hash::Util::FieldHash" doesn't
254       address the serialization problems.
255
256   The Generic Object
257       Classes based on the "id()" function (and hence classes based on
258       "idhash()" and "fieldhash()") show a peculiar behavior in that the
259       class name can be used like an object.  Specifically, methods that set
260       or read data associated with an object continue to work as class
261       methods, just as if the class name were an object, distinct from all
262       other objects, with its own data.  This object may be called the
263       generic object of the class.
264
265       This works because field hashes respond to keys that are not references
266       like a normal hash would and use the string offered as the hash key.
267       Thus, if a method is called as a class method, the field hash is
268       presented with the class name instead of an object and blithely uses it
269       as a key.  Since the keys of real objects are decimal numbers, there is
270       no conflict and the slot in the field hash can be used like any other.
271       The "id()" function behaves correspondingly with respect to non-
272       reference arguments.
273
274       Two possible uses (besides ignoring the property) come to mind.  A
275       singleton class could be implemented this using the generic object.  If
276       necessary, an "init()" method could die or ignore calls with actual
277       objects (references), so only the generic object will ever exist.
278
279       Another use of the generic object would be as a template.  It is a
280       convenient place to store class-specific defaults for various fields to
281       be used in actual object initialization.
282
283       Usually, the feature can be entirely ignored.  Calling object methods
284       as class methods normally leads to an error and isn't used routinely
285       anywhere.  It may be a problem that this error isn't indicated by a
286       class with a generic object.
287
288   How to use Field Hashes
289       Traditionally, the definition of an inside-out class contains a bare
290       block inside which a number of lexical hashes are declared and the
291       basic accessor methods defined, usually through
292       "Scalar::Util::refaddr".  Further methods may be defined outside this
293       block.  There has to be a DESTROY method and, for thread support, a
294       CLONE method.
295
296       When field hashes are used, the basic structure remains the same.  Each
297       lexical hash will be made a field hash.  The call to "refaddr" can be
298       omitted from the accessor methods.  DESTROY and CLONE methods are not
299       necessary.
300
301       If you have an existing inside-out class, simply making all hashes
302       field hashes with no other change should make no difference.  Through
303       the calls to "refaddr" or equivalent, the field hashes never get to see
304       a reference and work like normal hashes.  Your DESTROY (and CLONE)
305       methods are still needed.
306
307       To make the field hashes kick in, it is easiest to redefine "refaddr"
308       as
309
310           sub refaddr { shift }
311
312       instead of importing it from "Scalar::Util".  It should now be possible
313       to disable DESTROY and CLONE.  Note that while it isn't disabled,
314       DESTROY will be called before the garbage collection of field hashes,
315       so it will be invoked with a functional object and will continue to
316       function.
317
318       It is not desirable to import the functions "fieldhash" and/or
319       "fieldhashes" into every class that is going to use them.  They are
320       only used once to set up the class.  When the class is up and running,
321       these functions serve no more purpose.
322
323       If there are only a few field hashes to declare, it is simplest to
324
325           use Hash::Util::FieldHash;
326
327       early and call the functions qualified:
328
329           Hash::Util::FieldHash::fieldhash my %foo;
330
331       Otherwise, import the functions into a convenient package like "HUF"
332       or, more general, "Aux"
333
334           {
335               package Aux;
336               use Hash::Util::FieldHash ':all';
337           }
338
339       and call
340
341           Aux::fieldhash my %foo;
342
343       as needed.
344
345   Garbage-Collected Hashes
346       Garbage collection in a field hash means that entries will
347       "spontaneously" disappear when the object that created them disappears.
348       That must be borne in mind, especially when looping over a field hash.
349       If anything you do inside the loop could cause an object to go out of
350       scope, a random key may be deleted from the hash you are looping over.
351       That can throw the loop iterator, so it's best to cache a consistent
352       snapshot of the keys and/or values and loop over that.  You will still
353       have to check that a cached entry still exists when you get to it.
354
355       Garbage collection can be confusing when keys are created in a field
356       hash from normal scalars as well as references.  Once a reference is
357       used with a field hash, the entry will be collected, even if it was
358       later overwritten with a plain scalar key (every positive integer is a
359       candidate).  This is true even if the original entry was deleted in the
360       meantime.  In fact, deletion from a field hash, and also a test for
361       existence constitute use in this sense and create a liability to delete
362       the entry when the reference goes out of scope.  If you happen to
363       create an entry with an identical key from a string or integer, that
364       will be collected instead.  Thus, mixed use of references and plain
365       scalars as field hash keys is not entirely supported.
366

EXAMPLES

368       The examples show a very simple class that implements a name,
369       consisting of a first and last name (no middle initial).  The name
370       class has four methods:
371
372       ·   "init()"
373
374           An object method that initializes the first and last name to its
375           two arguments. If called as a class method, "init()" creates an
376           object in the given class and initializes that.
377
378       ·   "first()"
379
380           Retrieve the first name
381
382       ·   "last()"
383
384           Retrieve the last name
385
386       ·   "name()"
387
388           Retrieve the full name, the first and last name joined by a blank.
389
390       The examples show this class implemented with different levels of
391       support by "Hash::Util::FieldHash".  All supported combinations are
392       shown.  The difference between implementations is often quite small.
393       The implementations are:
394
395       ·   "Name_hash"
396
397           A conventional (not inside-out) implementation where an object is a
398           hash that stores the field values, without support by
399           "Hash::Util::FieldHash".  This implementation doesn't allow
400           arbitrary inheritance.
401
402       ·   "Name_id"
403
404           Inside-out implementation based on the "id()" function.  It needs a
405           "DESTROY" method.  For thread support a "CLONE" method (not shown)
406           would also be needed.  Instead of "Hash::Util::FieldHash::id()" the
407           function "Scalar::Util::refaddr" could be used with very little
408           functional difference.  This is the basic pattern of an inside-out
409           class.
410
411       ·   "Name_idhash"
412
413           Idhash-based inside-out implementation.  Like "Name_id" it needs a
414           "DESTROY" method and would need "CLONE" for thread support.
415
416       ·   "Name_id_reg"
417
418           Inside-out implementation based on the "id()" function with
419           explicit object registry.  No destructor is needed and objects are
420           thread safe.
421
422       ·   "Name_idhash_reg"
423
424           Idhash-based inside-out implementation with explicit object
425           registry.  No destructor is needed and objects are thread safe.
426
427       ·   "Name_fieldhash"
428
429           FieldHash-based inside-out implementation.  Object registry happens
430           automatically.  No destructor is needed and objects are thread
431           safe.
432
433       These examples are realized in the code below, which could be copied to
434       a file Example.pm.
435
436   Example 1
437           use strict; use warnings;
438
439           {
440               package Name_hash;  # standard implementation: the
441                                   # object is a hash
442               sub init {
443                   my $obj = shift;
444                   my ($first, $last) = @_;
445                   # create an object if called as class method
446                   $obj = bless {}, $obj unless ref $obj;
447                   $obj->{ first} = $first;
448                   $obj->{ last} = $last;
449                   $obj;
450               }
451
452               sub first { shift()->{ first} }
453               sub last { shift()->{ last} }
454
455               sub name {
456                   my $n = shift;
457                   join ' ' => $n->first, $n->last;
458               }
459
460           }
461
462           {
463               package Name_id;
464               use Hash::Util::FieldHash qw(id);
465
466               my (%first, %last);
467
468               sub init {
469                   my $obj = shift;
470                   my ($first, $last) = @_;
471                   # create an object if called as class method
472                   $obj = bless \ my $o, $obj unless ref $obj;
473                   $first{ id $obj} = $first;
474                   $last{ id $obj} = $last;
475                   $obj;
476               }
477
478               sub first { $first{ id shift()} }
479               sub last { $last{ id shift()} }
480
481               sub name {
482                   my $n = shift;
483                   join ' ' => $n->first, $n->last;
484               }
485
486               sub DESTROY {
487                   my $id = id shift;
488                   delete $first{ $id};
489                   delete $last{ $id};
490               }
491
492           }
493
494           {
495               package Name_idhash;
496               use Hash::Util::FieldHash;
497
498               Hash::Util::FieldHash::idhashes( \ my (%first, %last) );
499
500               sub init {
501                   my $obj = shift;
502                   my ($first, $last) = @_;
503                   # create an object if called as class method
504                   $obj = bless \ my $o, $obj unless ref $obj;
505                   $first{ $obj} = $first;
506                   $last{ $obj} = $last;
507                   $obj;
508               }
509
510               sub first { $first{ shift()} }
511               sub last { $last{ shift()} }
512
513               sub name {
514                   my $n = shift;
515                   join ' ' => $n->first, $n->last;
516               }
517
518               sub DESTROY {
519                   my $n = shift;
520                   delete $first{ $n};
521                   delete $last{ $n};
522               }
523
524           }
525
526           {
527               package Name_id_reg;
528               use Hash::Util::FieldHash qw(id register);
529
530               my (%first, %last);
531
532               sub init {
533                   my $obj = shift;
534                   my ($first, $last) = @_;
535                   # create an object if called as class method
536                   $obj = bless \ my $o, $obj unless ref $obj;
537                   register( $obj, \ (%first, %last) );
538                   $first{ id $obj} = $first;
539                   $last{ id $obj} = $last;
540                   $obj;
541               }
542
543               sub first { $first{ id shift()} }
544               sub last { $last{ id shift()} }
545
546               sub name {
547                   my $n = shift;
548                   join ' ' => $n->first, $n->last;
549               }
550           }
551
552           {
553               package Name_idhash_reg;
554               use Hash::Util::FieldHash qw(register);
555
556               Hash::Util::FieldHash::idhashes \ my (%first, %last);
557
558               sub init {
559                   my $obj = shift;
560                   my ($first, $last) = @_;
561                   # create an object if called as class method
562                   $obj = bless \ my $o, $obj unless ref $obj;
563                   register( $obj, \ (%first, %last) );
564                   $first{ $obj} = $first;
565                   $last{ $obj} = $last;
566                   $obj;
567               }
568
569               sub first { $first{ shift()} }
570               sub last { $last{ shift()} }
571
572               sub name {
573                   my $n = shift;
574                   join ' ' => $n->first, $n->last;
575               }
576           }
577
578           {
579               package Name_fieldhash;
580               use Hash::Util::FieldHash;
581
582               Hash::Util::FieldHash::fieldhashes \ my (%first, %last);
583
584               sub init {
585                   my $obj = shift;
586                   my ($first, $last) = @_;
587                   # create an object if called as class method
588                   $obj = bless \ my $o, $obj unless ref $obj;
589                   $first{ $obj} = $first;
590                   $last{ $obj} = $last;
591                   $obj;
592               }
593
594               sub first { $first{ shift()} }
595               sub last { $last{ shift()} }
596
597               sub name {
598                   my $n = shift;
599                   join ' ' => $n->first, $n->last;
600               }
601           }
602
603           1;
604
605       To exercise the various implementations the script below can be used.
606
607       It sets up a class "Name" that is a mirror of one of the implementation
608       classes "Name_hash", "Name_id", ..., "Name_fieldhash".  That determines
609       which implementation is run.
610
611       The script first verifies the function of the "Name" class.
612
613       In the second step, the free inheritability of the implementation (or
614       lack thereof) is demonstrated.  For this purpose it constructs a class
615       called "NamedFile" which is a common subclass of "Name" and the
616       standard class "IO::File".  This puts inheritability to the test
617       because objects of "IO::File" must be globrefs.  Objects of "NamedFile"
618       should behave like a file opened for reading and also support the
619       "name()" method.  This class juncture works with exception of the
620       "Name_hash" implementation, where object initialization fails because
621       of the incompatibility of object bodies.
622
623   Example 2
624           use strict; use warnings; $| = 1;
625
626           use Example;
627
628           {
629               package Name;
630               use parent 'Name_id';  # define here which implementation to run
631           }
632
633
634           # Verify that the base package works
635           my $n = Name->init(qw(Albert Einstein));
636           print $n->name, "\n";
637           print "\n";
638
639           # Create a named file handle (See definition below)
640           my $nf = NamedFile->init(qw(/tmp/x Filomena File));
641           # use as a file handle...
642           for ( 1 .. 3 ) {
643               my $l = <$nf>;
644               print "line $_: $l";
645           }
646           # ...and as a Name object
647           print "...brought to you by ", $nf->name, "\n";
648           exit;
649
650
651           # Definition of NamedFile
652           package NamedFile;
653           use parent 'Name';
654           use parent 'IO::File';
655
656           sub init {
657               my $obj = shift;
658               my ($file, $first, $last) = @_;
659               $obj = $obj->IO::File::new() unless ref $obj;
660               $obj->open($file) or die "Can't read '$file': $!";
661               $obj->Name::init($first, $last);
662           }
663           __END__
664

GUTS

666       To make "Hash::Util::FieldHash" work, there were two changes to perl
667       itself.  "PERL_MAGIC_uvar" was made available for hashes, and weak
668       references now call uvar "get" magic after a weakref has been cleared.
669       The first feature is used to make field hashes intercept their keys
670       upon access.  The second one triggers garbage collection.
671
672   The "PERL_MAGIC_uvar" interface for hashes
673       "PERL_MAGIC_uvar" get magic is called from "hv_fetch_common" and
674       "hv_delete_common" through the function "hv_magic_uvar_xkey", which
675       defines the interface.  The call happens for hashes with "uvar" magic
676       if the "ufuncs" structure has equal values in the "uf_val" and "uf_set"
677       fields.  Hashes are unaffected if (and as long as) these fields hold
678       different values.
679
680       Upon the call, the "mg_obj" field will hold the hash key to be
681       accessed.  Upon return, the "SV*" value in "mg_obj" will be used in
682       place of the original key in the hash access.  The integer index value
683       in the first parameter will be the "action" value from
684       "hv_fetch_common", or -1 if the call is from "hv_delete_common".
685
686       This is a template for a function suitable for the "uf_val" field in a
687       "ufuncs" structure for this call.  The "uf_set" and "uf_index" fields
688       are irrelevant.
689
690           IV watch_key(pTHX_ IV action, SV* field) {
691               MAGIC* mg = mg_find(field, PERL_MAGIC_uvar);
692               SV* keysv = mg->mg_obj;
693               /* Do whatever you need to.  If you decide to
694                  supply a different key newkey, return it like this
695               */
696               sv_2mortal(newkey);
697               mg->mg_obj = newkey;
698               return 0;
699           }
700
701   Weakrefs call uvar magic
702       When a weak reference is stored in an "SV" that has "uvar" magic, "set"
703       magic is called after the reference has gone stale.  This hook can be
704       used to trigger further garbage-collection activities associated with
705       the referenced object.
706
707   How field hashes work
708       The three features of key hashes, key replacement, thread support, and
709       garbage collection are supported by a data structure called the object
710       registry.  This is a private hash where every object is stored.  An
711       "object" in this sense is any reference (blessed or unblessed) that has
712       been used as a field hash key.
713
714       The object registry keeps track of references that have been used as
715       field hash keys.  The keys are generated from the reference address
716       like in a field hash (though the registry isn't a field hash).  Each
717       value is a weak copy of the original reference, stored in an "SV" that
718       is itself magical ("PERL_MAGIC_uvar" again).  The magical structure
719       holds a list (another hash, really) of field hashes that the reference
720       has been used with.  When the weakref becomes stale, the magic is
721       activated and uses the list to delete the reference from all field
722       hashes it has been used with.  After that, the entry is removed from
723       the object registry itself.  Implicitly, that frees the magic structure
724       and the storage it has been using.
725
726       Whenever a reference is used as a field hash key, the object registry
727       is checked and a new entry is made if necessary.  The field hash is
728       then added to the list of fields this reference has used.
729
730       The object registry is also used to repair a field hash after thread
731       cloning.  Here, the entire object registry is processed.  For every
732       reference found there, the field hashes it has used are visited and the
733       entry is updated.
734
735   Internal function Hash::Util::FieldHash::_fieldhash
736           # test if %hash is a field hash
737           my $result = _fieldhash \ %hash, 0;
738
739           # make %hash a field hash
740           my $result = _fieldhash \ %hash, 1;
741
742       "_fieldhash" is the internal function used to create field hashes.  It
743       takes two arguments, a hashref and a mode.  If the mode is boolean
744       false, the hash is not changed but tested if it is a field hash.  If
745       the hash isn't a field hash the return value is boolean false.  If it
746       is, the return value indicates the mode of field hash.  When called
747       with a boolean true mode, it turns the given hash into a field hash of
748       this mode, returning the mode of the created field hash.  "_fieldhash"
749       does not erase the given hash.
750
751       Currently there is only one type of field hash, and only the boolean
752       value of the mode makes a difference, but that may change.
753

AUTHOR

755       Anno Siegel (ANNO) wrote the xs code and the changes in perl proper
756       Jerry Hedden (JDHEDDEN) made it faster
757
759       Copyright (C) 2006-2007 by (Anno Siegel)
760
761       This library is free software; you can redistribute it and/or modify it
762       under the same terms as Perl itself, either Perl version 5.8.7 or, at
763       your option, any later version of Perl 5 you may have available.
764
765
766
767perl v5.30.2                      2020-03-27        Hash::Util::FieldHash(3pm)
Impressum