local-lib5/man/man3/FreezeThaw.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "FreezeThaw 3"
 127 .TH FreezeThaw 3 "2010-04-03" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 FreezeThaw \- converting Perl structures to strings and back.
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 5
 137 \&  use FreezeThaw qw(freeze thaw cmpStr safeFreeze cmpStrHard);
 138 \&  $string = freeze $data1, $data2, $data3;
 139 \&  ...
 140 \&  ($olddata1, $olddata2, $olddata3) = thaw $string;
 141 \&  if (cmpStr($olddata2,$data2) == 0) {print "OK!"}
 142 .Ve
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 Converts data to/from stringified form, appropriate for
 146 saving\-to/reading\-from permanent storage.
 147 .PP
 148 Deals with objects, circular lists, repeated appearence of the same
 149 refence. Does not deal with overloaded \fIstringify\fR operator yet.
 150 .SH "EXPORT"
 151 .IX Header "EXPORT"
 152 .IP "Default" 12
 153 .IX Item "Default"
 154 None.
 155 .IP "Exportable" 12
 156 .IX Item "Exportable"
 157 \&\f(CW\*(C`freeze thaw cmpStr cmpStrHard safeFreeze\*(C'\fR.
 158 .SH "User API"
 159 .IX Header "User API"
 160 .ie n .IP """cmpStr""" 12
 161 .el .IP "\f(CWcmpStr\fR" 12
 162 .IX Item "cmpStr"
 163 analogue of \f(CW\*(C`cmp\*(C'\fR for data. Takes two arguments and compares them as
 164 separate entities.
 165 .ie n .IP """cmpStrHard""" 12
 166 .el .IP "\f(CWcmpStrHard\fR" 12
 167 .IX Item "cmpStrHard"
 168 analogue of \f(CW\*(C`cmp\*(C'\fR for data. Takes two arguments and compares them
 169 considered as a group.
 170 .ie n .IP """freeze""" 12
 171 .el .IP "\f(CWfreeze\fR" 12
 172 .IX Item "freeze"
 173 returns a string that encupsulates its arguments (considered as a
 174 group). \f(CW\*(C`thaw\*(C'\fRing this string leads to a fatal error if arguments to
 175 \&\f(CW\*(C`freeze\*(C'\fR contained references to \f(CW\*(C`GLOB\*(C'\fRs and \f(CW\*(C`CODE\*(C'\fRs.
 176 .ie n .IP """safeFreeze""" 12
 177 .el .IP "\f(CWsafeFreeze\fR" 12
 178 .IX Item "safeFreeze"
 179 returns a string that encupsulates its arguments (considered as a
 180 group). The result is \f(CW\*(C`thaw\*(C'\fRable in the same process. \f(CW\*(C`thaw\*(C'\fRing the
 181 result in a different process should result in a fatal error if
 182 arguments to \f(CW\*(C`safeFreeze\*(C'\fR contained references to \f(CW\*(C`GLOB\*(C'\fRs and
 183 \&\f(CW\*(C`CODE\*(C'\fRs.
 184 .ie n .IP """thaw""" 12
 185 .el .IP "\f(CWthaw\fR" 12
 186 .IX Item "thaw"
 187 takes one string argument and returns an array. The elements of the
 188 array are \*(L"equivalent\*(R" to arguments of the \f(CW\*(C`freeze\*(C'\fR command that
 189 created the string. Can result in a fatal error (see above).
 190 .SH "Developer API"
 191 .IX Header "Developer API"
 192 \&\f(CW\*(C`FreezeThaw\*(C'\fR \f(CW\*(C`freeze\*(C'\fRs and \f(CW\*(C`thaw\*(C'\fRs data blessed in some package by
 193 calling methods \f(CW\*(C`Freeze\*(C'\fR and \f(CW\*(C`Thaw\*(C'\fR in the package. The fallback
 194 methods are provided by the \f(CW\*(C`FreezeThaw\*(C'\fR itself. The fallback
 195 \&\f(CW\*(C`Freeze\*(C'\fR freezes the \*(L"content\*(R" of blessed object (from Perl point of
 196 view). The fallback \f(CW\*(C`Thaw\*(C'\fR blesses the \f(CW\*(C`thaw\*(C'\fRed data back into the package.
 197 .PP
 198 So the package needs to define its own methods only if the fallback
 199 methods will fail (for example, for a lot of data the \*(L"content\*(R" of an
 200 object is an address of some \fBC\fR data). The methods are called like
 201 .PP
 202 .Vb 2
 203 \&  $newcooky = $obj\->Freeze($cooky);
 204 \&  $obj = Package\->Thaw($content,$cooky);
 205 .Ve
 206 .PP
 207 To save and restore the data the following method are applicable:
 208 .PP
 209 .Vb 1
 210 \&  $cooky\->FreezeScalar($data,$ignorePackage,$noduplicate);
 211 .Ve
 212 .PP
 213 during \fIFreeze()\fRing, and
 214 .PP
 215 .Vb 1
 216 \&  $data = $cooky\->ThawScalar;
 217 .Ve
 218 .PP
 219 Two optional arguments \f(CW$ignorePackage\fR and \f(CW$noduplicate\fR regulate
 220 whether the freezing should not call the methods even if \f(CW$data\fR is a
 221 reference to a blessed object, and whether the data should not be
 222 marked as seen already even if it was seen before. The default methods
 223 .PP
 224 .Vb 4
 225 \&  sub UNIVERSAL::Freeze {
 226 \&    my ($obj, $cooky) = (shift, shift);
 227 \&    $cooky\->FreezeScalar($obj,1,1);
 228 \&  }
 229 \&
 230 \&  sub UNIVERSAL::Thaw {
 231 \&    my ($package, $cooky) = (shift, shift);
 232 \&    my $obj = $cooky\->ThawScalar;
 233 \&    bless $obj, $package;
 234 \&  }
 235 .Ve
 236 .PP
 237 call the \f(CW\*(C`FreezeScalar\*(C'\fR method of the \f(CW$cooky\fR since the freezing
 238 engine will see the data the second time during this call. Indeed, it
 239 is the freezing engine who calls \fIUNIVERSAL::Freeze()\fR, and it calls it
 240 because it needs to freeze \f(CW$obj\fR. The above call to
 241 \&\f(CW$cooky\fR\->\fIFreezeScalar()\fR handles the same data back to engine, but
 242 because flags are different, the code does not cycle.
 243 .PP
 244 Freezing and thawing \f(CW$cooky\fR also allows the following additional methods:
 245 .PP
 246 .Vb 1
 247 \&  $cooky\->isSafe;
 248 .Ve
 249 .PP
 250 to find out whether the current freeze was initiated by \f(CW\*(C`freeze\*(C'\fR or
 251 \&\f(CW\*(C`safeFreeze\*(C'\fR command. Analogous method for thaw \f(CW$cooky\fR returns
 252 whether the current thaw operation is considered safe (i.e., either
 253 does not contain cached elsewhere data, or comes from the same
 254 application). You can use
 255 .PP
 256 .Vb 1
 257 \&  $cooky\->makeSafe;
 258 .Ve
 259 .PP
 260 to prohibit cached data for the duration of the rest of freezing or
 261 thawing of current object.
 262 .PP
 263 Two methods
 264 .PP
 265 .Vb 2
 266 \&  $value = $cooky\->repeatedOK;
 267 \&  $cooky\->noRepeated;           # Now repeated are prohibited
 268 .Ve
 269 .PP
 270 allow to find out/change the current setting for allowing repeated
 271 references.
 272 .PP
 273 If you want to flush the cache of saved objects you can use
 274 .PP
 275 .Vb 1
 276 \&  FreezeThaw\->flushCache;
 277 .Ve
 278 .PP
 279 this can invalidate some frozen string, so that thawing them will
 280 result in fatal error.
 281 .SS "Instantiating"
 282 .IX Subsection "Instantiating"
 283 Sometimes, when an object from a package is recreated in presense of
 284 repeated references, it is not safe to recreate the internal structure
 285 of an object in one step. In such a situation recreation of an object
 286 is carried out in two steps: in the first the object is \f(CW\*(C`allocate\*(C'\fRd,
 287 in the second it is \f(CW\*(C`instantiate\*(C'\fRd.
 288 .PP
 289 The restriction is that during the \fIallocation\fR step you cannot use any
 290 reference to any Perl object that can be referenced from any other
 291 place. This restriction is applied since that object may not exist yet.
 292 .PP
 293 Correspondingly, during \fIinstantiation\fR step the previosly \fIallocated\fR
 294 object should be \f(CW\*(C`filled\*(C'\fR, i.e., it can be changed in any way such
 295 that the references to this object remain valid.
 296 .PP
 297 The methods are called like this:
 298 .PP
 299 .Vb 4
 300 \&  $pre_object_ref = Package\->Allocate($pre_pre_object_ref);
 301 \&        # Returns reference
 302 \&  Package\->Instantiate($pre_object_ref,$cooky);
 303 \&        # Converts into reference to blessed object
 304 .Ve
 305 .PP
 306 The reverse operations are
 307 .PP
 308 .Vb 2
 309 \&  $object_ref\->FreezeEmpty($cooky);
 310 \&  $object_ref\->FreezeInstance($cooky);
 311 .Ve
 312 .PP
 313 during these calls object can \f(CW\*(C`freezeScalar\*(C'\fR some information (in a
 314 usual way) that will be used during \f(CW\*(C`Allocate\*(C'\fR and \f(CW\*(C`Instantiate\*(C'\fR
 315 calls (via \f(CW\*(C`thawScalar\*(C'\fR). Note that the return value of
 316 \&\f(CW\*(C`FreezeEmpty\*(C'\fR is cached during the phase of creation of uninialized
 317 objects. This \fBmust\fR be used like this: the return value is the
 318 reference to the created object, so it is not destructed until other
 319 objects are created, thus the frozen values of the different objects
 320 will not share the same references. Example of bad result:
 321 .PP
 322 .Vb 1
 323 \&  $o1\->FreezeEmpty($cooky)
 324 .Ve
 325 .PP
 326 freezes \f(CW\*(C`{}\*(C'\fR, and \f(CW\*(C`$o2\->FreezeEmpty($cooky)\*(C'\fR makes the same. Now
 327 nobody guaranties that that these two copies of \f(CW\*(C`{}\*(C'\fR are different,
 328 unless a reference to the first one is preserved during the call to
 329 \&\f(CW\*(C`$o2\->FreezeEmpty($cooky)\*(C'\fR. If \f(CW\*(C`$o1\->FreezeEmpty($cooky)\*(C'\fR
 330 returns the value of \f(CW\*(C`{}\*(C'\fR it uses, it will be preserved by the
 331 engine.
 332 .PP
 333 The helper function \f(CW\*(C`FreezeThaw::copyContents\*(C'\fR is provided for
 334 simplification of instantiation. The syntax is
 335 .PP
 336 .Vb 1
 337 \&  FreezeThaw::copyContents $to, $from;
 338 .Ve
 339 .PP
 340 The function copies contents the object \f(CW$from\fR point to into what the
 341 object \f(CW$to\fR points to (including package for blessed references). Both
 342 arguments should be references.
 343 .PP
 344 The default methods are provided. They do the following:
 345 .ie n .IP """FreezeEmpty""" 12
 346 .el .IP "\f(CWFreezeEmpty\fR" 12
 347 .IX Item "FreezeEmpty"
 348 Freezes an \fIempty\fR object of underlying type.
 349 .ie n .IP """FreezeInstance""" 12
 350 .el .IP "\f(CWFreezeInstance\fR" 12
 351 .IX Item "FreezeInstance"
 352 Calls \f(CW\*(C`Freeze\*(C'\fR.
 353 .ie n .IP """Allocate""" 12
 354 .el .IP "\f(CWAllocate\fR" 12
 355 .IX Item "Allocate"
 356 Thaws what was frozen by \f(CW\*(C`FreezeEmpty\*(C'\fR.
 357 .ie n .IP """Instantiate""" 12
 358 .el .IP "\f(CWInstantiate\fR" 12
 359 .IX Item "Instantiate"
 360 Thaws what was frozen by \f(CW\*(C`FreezeInstance\*(C'\fR, uses \f(CW\*(C`copyContents\*(C'\fR to
 361 transfer this to the \f(CW$pre_object\fR.
 362 .SH "BUGS and LIMITATIONS"
 363 .IX Header "BUGS and LIMITATIONS"
 364 A lot of objects are blessed in some obscure packages by \s-1XSUB\s0
 365 typemaps. It is not clear how to (automatically) prevent the
 366 \&\f(CW\*(C`UNIVERSAL\*(C'\fR methods to be called for objects in these packages.
 367 .PP
 368 The objects which can survive \fIfreeze()\fR/\fIthaw()\fR cycle must also survive a
 369 change of a \*(L"member\*(R" to an equal member.  Say, after
 370 .PP
 371 .Vb 2
 372 \&  $a = [a => 3];
 373 \&  $a\->{b} = \e $a\->{a};
 374 .Ve
 375 .PP
 376 \&\f(CW$a\fR satisfies
 377 .PP
 378 .Vb 1
 379 \&  $a\->{b} == \e $a\->{a}
 380 .Ve
 381 .PP
 382 This property will be broken by \fIfreeze()\fR/\fIthaw()\fR, but it is also broken by
 383 .PP
 384 .Vb 1
 385 \&  $a\->{a} = delete $a\->{a};
 386 .Ve