Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FreezeThaw(3)	      User Contributed Perl Documentation	 FreezeThaw(3)

NAME
       FreezeThaw - converting Perl structures to strings and back.

SYNOPSIS
	 use FreezeThaw	qw(freeze thaw cmpStr safeFreeze cmpStrHard);
	 $string = freeze $data1, $data2, $data3;
	 ...
	 ($olddata1, $olddata2,	$olddata3) = thaw $string;
	 if (cmpStr($olddata2,$data2) == 0) {print "OK!"}

DESCRIPTION
       Converts	data to/from stringified form, appropriate for
       saving-to/reading-from permanent	storage.

       Deals with objects, circular lists, repeated appearence of the same
       refence.	Does not deal with overloaded stringify	operator yet.

EXPORT
       Default	   None.

       Exportable  "freeze thaw	cmpStr cmpStrHard safeFreeze".

User API
       "cmpStr"	   analogue of "cmp" for data. Takes two arguments and
		   compares them as separate entities.

       "cmpStrHard"
		   analogue of "cmp" for data. Takes two arguments and
		   compares them considered as a group.

       "freeze"	   returns a string that encupsulates its arguments
		   (considered as a group). "thaw"ing this string leads	to a
		   fatal error if arguments to "freeze"	contained references
		   to "GLOB"s and "CODE"s.

       "safeFreeze"
		   returns a string that encupsulates its arguments
		   (considered as a group). The	result is "thaw"able in	the
		   same	process. "thaw"ing the result in a different process
		   should result in a fatal error if arguments to "safeFreeze"
		   contained references	to "GLOB"s and "CODE"s.

       "thaw"	   takes one string argument and returns an array. The
		   elements of the array are "equivalent" to arguments of the
		   "freeze" command that created the string. Can result	in a
		   fatal error (see above).

Developer API
       "FreezeThaw" "freeze"s and "thaw"s data blessed in some package by
       calling methods "Freeze"	and "Thaw" in the package. The fallback
       methods are provided by the "FreezeThaw"	itself.	The fallback "Freeze"
       freezes the "content" of	blessed	object (from Perl point	of view). The
       fallback	"Thaw" blesses the "thaw"ed data back into the package.

       So the package needs to define its own methods only if the fallback
       methods will fail (for example, for a lot of data the "content" of an
       object is an address of some C data). The methods are called like

	 $newcooky = $obj->Freeze($cooky);
	 $obj =	Package->Thaw($content,$cooky);

       To save and restore the data the	following method are applicable:

	 $cooky->FreezeScalar($data,$ignorePackage,$noduplicate);

       during Freeze()ing, and

	 $data = $cooky->ThawScalar;

       Two optional arguments $ignorePackage and $noduplicate regulate whether
       the freezing should not call the	methods	even if	$data is a reference
       to a blessed object, and	whether	the data should	not be marked as seen
       already even if it was seen before. The default methods

	 sub UNIVERSAL::Freeze {
	   my ($obj, $cooky) = (shift, shift);
	   $cooky->FreezeScalar($obj,1,1);
	 }

	 sub UNIVERSAL::Thaw {
	   my ($package, $cooky) = (shift, shift);
	   my $obj = $cooky->ThawScalar;
	   bless $obj, $package;
	 }

       call the	"FreezeScalar" method of the $cooky since the freezing engine
       will see	the data the second time during	this call. Indeed, it is the
       freezing	engine who calls UNIVERSAL::Freeze(), and it calls it because
       it needs	to freeze $obj.	The above call to $cooky->FreezeScalar()
       handles the same	data back to engine, but because flags are different,
       the code	does not cycle.

       Freezing	and thawing $cooky also	allows the following additional
       methods:

	 $cooky->isSafe;

       to find out whether the current freeze was initiated by "freeze"	or
       "safeFreeze" command. Analogous method for thaw $cooky returns whether
       the current thaw	operation is considered	safe (i.e., either does	not
       contain cached elsewhere	data, or comes from the	same application). You
       can use

	 $cooky->makeSafe;

       to prohibit cached data for the duration	of the rest of freezing	or
       thawing of current object.

       Two methods

	 $value	= $cooky->repeatedOK;
	 $cooky->noRepeated;	       # Now repeated are prohibited

       allow to	find out/change	the current setting for	allowing repeated
       references.

       If you want to flush the	cache of saved objects you can use

	 FreezeThaw->flushCache;

       this can	invalidate some	frozen string, so that thawing them will
       result in fatal error.

   Instantiating
       Sometimes, when an object from a	package	is recreated in	presense of
       repeated	references, it is not safe to recreate the internal structure
       of an object in one step. In such a situation recreation	of an object
       is carried out in two steps: in the first the object is "allocate"d, in
       the second it is	"instantiate"d.

       The restriction is that during the allocation step you cannot use any
       reference to any	Perl object that can be	referenced from	any other
       place. This restriction is applied since	that object may	not exist yet.

       Correspondingly,	during instantiation step the previosly	allocated
       object should be	"filled", i.e.,	it can be changed in any way such that
       the references to this object remain valid.

       The methods are called like this:

	 $pre_object_ref = Package->Allocate($pre_pre_object_ref);
	       # Returns reference
	 Package->Instantiate($pre_object_ref,$cooky);
	       # Converts into reference to blessed object

       The reverse operations are

	 $object_ref->FreezeEmpty($cooky);
	 $object_ref->FreezeInstance($cooky);

       during these calls object can "freezeScalar" some information (in a
       usual way) that will be used during "Allocate" and "Instantiate"	calls
       (via "thawScalar"). Note	that the return	value of "FreezeEmpty" is
       cached during the phase of creation of uninialized objects. This	must
       be used like this: the return value is the reference to the created
       object, so it is	not destructed until other objects are created,	thus
       the frozen values of the	different objects will not share the same
       references. Example of bad result:

	 $o1->FreezeEmpty($cooky)

       freezes "{}", and "$o2->FreezeEmpty($cooky)" makes the same. Now	nobody
       guaranties that that these two copies of	"{}" are different, unless a
       reference to the	first one is preserved during the call to
       "$o2->FreezeEmpty($cooky)". If "$o1->FreezeEmpty($cooky)" returns the
       value of	"{}" it	uses, it will be preserved by the engine.

       The helper function "FreezeThaw::copyContents" is provided for
       simplification of instantiation.	The syntax is

	 FreezeThaw::copyContents $to, $from;

       The function copies contents the	object $from point to into what	the
       object $to points to (including package for blessed references).	Both
       arguments should	be references.

       The default methods are provided. They do the following:

       "FreezeEmpty"
		   Freezes an empty object of underlying type.

       "FreezeInstance"
		   Calls "Freeze".

       "Allocate"  Thaws what was frozen by "FreezeEmpty".

       "Instantiate"
		   Thaws what was frozen by "FreezeInstance", uses
		   "copyContents" to transfer this to the $pre_object.

BUGS and LIMITATIONS
       A lot of	objects	are blessed in some obscure packages by	XSUB typemaps.
       It is not clear how to (automatically) prevent the "UNIVERSAL" methods
       to be called for	objects	in these packages.

       The objects which can survive freeze()/thaw() cycle must	also survive a
       change of a "member" to an equal	member.	 Say, after

	 $a = [a => 3];
	 $a->{b} = \ $a->{a};

       $a satisfies

	 $a->{b} == \ $a->{a}

       This property will be broken by freeze()/thaw(),	but it is also broken
       by

	 $a->{a} = delete $a->{a};

perl v5.24.1			  2010-04-03			 FreezeThaw(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORT | User API | Developer API | BUGS and LIMITATIONS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=FreezeThaw&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help