hash::util::fieldhash.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Hash::Util::FieldHash 3"
.TH Hash::Util::FieldHash 3 "2007-12-18" "perl v5.10.0" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Hash::Util::FieldHash \- Support for Inside\-Out Classes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  ### Create fieldhashes
\&  use Hash::Util qw(fieldhash fieldhashes);
\&
\&  # Create a single field hash
\&  fieldhash my %foo;
\&
\&  # Create three at once...
\&  fieldhashes \e my(%foo, %bar, %baz);
\&  # ...or any number
\&  fieldhashes @hashrefs;
\&
\&  ### Create an idhash and register it for garbage collection
\&  use Hash::Util::FieldHash qw(idhash register);
\&  idhash my %name;
\&  my $object = \e do { my $o };
\&  # register the idhash for garbage collection with $object
\&  register($object, \e %name);
\&  # the following entry will be deleted when $object goes out of scope
\&  $name{$object} = \*(AqJohn Doe\*(Aq;
\&
\&  ### Register an ordinary hash for garbage collection
\&  use Hash::Util::FieldHash qw(id register);
\&  my %name;
\&  my $object = \e do { my $o };
\&  # register the hash %name for garbage collection of $object\*(Aqs id
\&  register $object, \e %name;
\&  # the following entry will be deleted when $object goes out of scope
\&  $name{id $object} = \*(AqJohn Doe\*(Aq;
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
\&\f(CW\*(C`Hash::Util::FieldHash\*(C'\fR offers a number of functions in support of
\&\*(L"The Inside-out Technique\*(R" of class construction.
.IP "id" 4
.IX Item "id"
.Vb 1
\&    id($obj)
.Ve
.Sp
Returns the reference address of a reference \f(CW$obj\fR.  If \f(CW$obj\fR is
not a reference, returns \f(CW$obj\fR.
.Sp
This function is a stand-in replacement for
Scalar::Util::refaddr, that is, it returns
the reference address of its argument as a numeric value.  The only
difference is that \f(CW\*(C`refaddr()\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR when given a
non-reference while \f(CW\*(C`id()\*(C'\fR returns its argument unchanged.
.Sp
\&\f(CW\*(C`id()\*(C'\fR also uses a caching technique that makes it faster when
the id of an object is requested often, but slower if it is needed
only once or twice.
.IP "id_2obj" 4
.IX Item "id_2obj"
.Vb 1
\&    $obj = id_2obj($id)
.Ve
.Sp
If \f(CW$id\fR is the id of a registered object (see \*(L"register\*(R"), returns
the object, otherwise an undefined value.  For registered objects this
is the inverse function of \f(CW\*(C`id()\*(C'\fR.
.IP "register" 4
.IX Item "register"
.Vb 2
\&    register($obj)
\&    register($obj, @hashrefs)
.Ve
.Sp
In the first form, registers an object to work with for the function
\&\f(CW\*(C`id_2obj()\*(C'\fR.  In the second form, it additionally marks the given
hashrefs down for garbage collection.  This means that when the object
goes out of scope, any entries in the given hashes under the key of
\&\f(CW\*(C`id($obj)\*(C'\fR will be deleted from the hashes.
.Sp
It is a fatal error to register a non-reference \f(CW$obj\fR.  Any non-hashrefs
among the following arguments are silently ignored.
.Sp
It is \fInot\fR an error to register the same object multiple times with
varying sets of hashrefs.  Any hashrefs that are not registered yet
will be added, others ignored.
.Sp
Registry also implies thread support.  When a new thread is created,
all references are replaced with new ones, including all objects.
If a hash uses the reference address of an object as a key, that
connection would be broken.  With a registered object, its id will
be updated in all hashes registered with it.
.IP "idhash" 4
.IX Item "idhash"
.Vb 1
\&    idhash my %hash
.Ve
.Sp
Makes an idhash from the argument, which must be a hash.
.Sp
An \fIidhash\fR works like a normal hash, except that it stringifies a
\&\fIreference used as a key\fR differently.  A reference is stringified
as if the \f(CW\*(C`id()\*(C'\fR function had been invoked on it, that is, its
reference address in decimal is used as the key.
.IP "idhashes" 4
.IX Item "idhashes"
.Vb 2
\&    idhashes \e my(%hash, %gnash, %trash)
\&    idhashes \e @hashrefs
.Ve
.Sp
Creates many idhashes from its hashref arguments.  Returns those
arguments that could be converted or their number in scalar context.
.IP "fieldhash" 4
.IX Item "fieldhash"
.Vb 1
\&    fieldhash %hash;
.Ve
.Sp
Creates a single fieldhash.  The argument must be a hash.  Returns
a reference to the given hash if successful, otherwise nothing.
.Sp
A \fIfieldhash\fR is, in short, an idhash with auto-registry.  When an
object (or, indeed, any reference) is used as a fieldhash key, the
fieldhash is automatically registered for garbage collection with
the object, as if \f(CW\*(C`register $obj, \e %fieldhash\*(C'\fR had been called.
.IP "fieldhashes" 4
.IX Item "fieldhashes"
.Vb 1
\&    fieldhashes @hashrefs;
.Ve
.Sp
Creates any number of field hashes.  Arguments must be hash references.
Returns the converted hashrefs in list context, their number in scalar
context.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A word on terminology:  I shall use the term \fIfield\fR for a scalar
piece of data that a class associates with an object.  Other terms that
have been used for this concept are \*(L"object variable\*(R", \*(L"(object) property\*(R",
\&\*(L"(object) attribute\*(R" and more.  Especially \*(L"attribute\*(R" has some currency
among Perl programmer, but that clashes with the \f(CW\*(C`attributes\*(C'\fR pragma.  The
term \*(L"field\*(R" also has some currency in this sense and doesn't seem
to conflict with other Perl terminology.
.PP
In Perl, an object is a blessed reference.  The standard way of associating
data with an object is to store the data inside the object's body, that is,
the piece of data pointed to by the reference.
.PP
In consequence, if two or more classes want to access an object they
\&\fImust\fR agree on the type of reference and also on the organization of
data within the object body.  Failure to agree on the type results in
immediate death when the wrong method tries to access an object.  Failure
to agree on data organization may lead to one class trampling over the
data of another.
.PP
This object model leads to a tight coupling between subclasses.
If one class wants to inherit from another (and both classes access
object data), the classes must agree about implementation details.
Inheritance can only be used among classes that are maintained together,
in a single source or not.
.PP
In particular, it is not possible to write general-purpose classes
in this technique, classes that can advertise themselves as \*(L"Put me
on your \f(CW@ISA\fR list and use my methods\*(R".  If the other class has different
ideas about how the object body is used, there is trouble.
.PP
For reference Name_hash in \*(L"Example 1\*(R" shows the standard implementation of
a simple class \f(CW\*(C`Name\*(C'\fR in the well-known hash based way.  It also demonstrates
the predictable failure to construct a common subclass \f(CW\*(C`NamedFile\*(C'\fR
of \f(CW\*(C`Name\*(C'\fR and the class \f(CW\*(C`IO::File\*(C'\fR (whose objects \fImust\fR be globrefs).
.PP
Thus, techniques are of interest that store object data \fInot\fR in
the object body but some other place.
.Sh "The Inside-out Technique"
.IX Subsection "The Inside-out Technique"