ot Namespace Reference

Object traversal utilities for printing, copying, freezing, and serialization. More...

Functions
template<typename T >
T *	Construct (T *array, size_t elems=1)
	Equivalent to mem::Construct, but exploits properties of shallow types.
template<typename T >
COMPILER_DEPRECATED void	Copy (const T &src, T *dest)
	Renamed InitCopy.
template<typename T >
T *	CopyConstruct (T dest, const T src, size_t elems=1)
	Equivalent to mem::CopyConstruct, but exploits properties of shallow types and does not require a copy constructor to be defined for traversed types.
template<typename T >
T *	Destruct (T *array, size_t elems=1)
	Equivalent to mem::Destruct, but exploits properties of shallow types.
template<typename T >
size_t	Freeze (char *block, const T &src)
	Copy an object's contents into flat buffer for easy transport, normalizing pointers to offsets into the buffer for fast reuse.
template<typename T >
size_t	FrozenSize (const T &obj)
	Determine the buffer size needed to store a frozen copy of an object.
template<typename T >
void	InitCopy (T *dest, const T &src)
	Copy an object into a specified destination.
template<typename T >
size_t	InitDeserialize (T dest, FILE stream)
	Read a serialized version of an object from a file stream, reconstructing its transients.
template<typename T >
void	InitThaw (T dest, const char block)
	Copy from a frozen object into a specified destination.
template<typename T >
COMPILER_DEPRECATED void	PointerFreeze (const T &obj, char *block)
	Renamed Freeze.
template<typename T >
COMPILER_DEPRECATED size_t	PointerFrozenSize (const T &obj)
	Renamed FrozenSize.
template<typename T >
COMPILER_DEPRECATED void	PointerRefreeze (const T src, char dest)
	Renamed SemiFreeze.
template<typename T >
COMPILER_DEPRECATED void	PointerRelocate (const char old_loc, char new_loc)
	Behavior similar to SemiCopy; beware memory leaks.
template<typename T >
COMPILER_DEPRECATED T *	PointerThaw (char *block)
	Renamed SemiThaw.
template<typename T >
void	Print (const T &obj, FILE *stream=stdout)
template<typename T >
const char *	Print (const T &obj, const char name, FILE stream=stdout)
	Pretty-print an object using the standard print format.
template<typename TPrintFormat , typename T >
void	Print (const T &obj, FILE *stream=stdout)
template<typename TPrintFormat , typename T >
const char *	Print (const T &obj, const char name, FILE stream=stdout)
	Pretty-print an object using a given print format.
template<typename T >
T *	RepeatConstruct (T *array, const T &init, size_t elems)
	Equivalent to mem::RepeatConstruct, but does not require a copy constructor to be defined for traversed types.
template<typename T >
T *	SemiCopy (char block, const char orig)
template<typename T >
T *	SemiCopy (char block, const T orig)
	Fixes the pointers and reconstructs transients of a semi-object assuming it has already been bit-copied into a new location.
template<typename T >
void	SemiDestruct (char *block)
template<typename T >
void	SemiDestruct (T *obj)
	Destructs a semi-object's transients and debug-poisons its memory.
template<typename T >
void	SemiFreeze (char block, const char orig)
template<typename T >
void	SemiFreeze (char block, const T orig)
	Re-freezes a semi-object assuming it has already been bit-copied into a new location.
template<typename T >
char *	SemiFreezeDestruct (char *block)
template<typename T >
char *	SemiFreezeDestruct (T *obj)
	Re-freezes a semi-object and destructs its transients.
template<typename T >
T *	SemiThaw (char *block)
	Thaws a frozen object by fixing pointers and reconstructing transients.
template<typename T >
size_t	Serialize (const T &obj, FILE *stream)
	Write a serialized version of an object to a file stream.
template<typename T >
size_t	SerialSize (const T &obj)
	Determine the length in bytes of a serialized version of an object.

Detailed Description

Object traversal utilities for printing, copying, freezing, and serialization.

These tools operate on all classes that invoke the OBJECT_TRAVERSAL macro or an equivalent, which includes all core FASTlib data structures. Specifically, they provide:

Pretty-printing for debugging or saving to XML
A generic copy routine that works on primitives, untraversed classes with copy constructors, and all traversed classes
Object "freezing", which copies the object's contents into a flat buffer for easy transport and fast reuse
Serialization and deserialization to and from file streams.

You can incorporate many of these functions as methods of your class with the OT_FREEZE_METHODS and OT_SERIALIZE_METHODS macors. Default OBJECT_TRAVERSAL already gives your class Print and InitCopy methods.

See also:: OBJECT_TRAVERSAL, OT_FREEZE_METHODS, OT_SERIALIZE_METHODS

Function Documentation

template<typename T >

T * ot::Construct	(	T *	array,
		size_t	elems = `1`
	)			`[inline]`

Equivalent to mem::Construct, but exploits properties of shallow types.

Definition at line 1918 of file otrav.h.

References mem::DebugPoison().

Referenced by ArrayList< std::pair< index_t, index_t > >::GrowTo(), ArrayList< std::pair< index_t, index_t > >::Init(), ArrayList< std::pair< index_t, index_t > >::Insert(), and ArrayList< std::pair< index_t, index_t > >::PushBack().

template<typename T >

COMPILER_DEPRECATED void ot::Copy	(	const T &	src,
		T *	dest
	)			`[inline]`

Renamed InitCopy.

Definition at line 1973 of file otrav.h.

References InitCopy().

template<typename T >

T * ot::CopyConstruct	(	T *	dest,
		const T *	src,
		size_t	elems = `1`
	)			`[inline]`

Equivalent to mem::CopyConstruct, but exploits properties of shallow types and does not require a copy constructor to be defined for traversed types.

Note the absense of DEBUG_INIT_OK. This ensures that this function works on arrays of unconstructed objects.

Definition at line 1948 of file otrav.h.

Referenced by ArrayList< std::pair< index_t, index_t > >::AppendCopy(), ArrayList< std::pair< index_t, index_t > >::InfixCopy(), ArrayList< std::pair< index_t, index_t > >::InitCopy(), ArrayList< std::pair< index_t, index_t > >::InsertCopy(), and ArrayList< std::pair< index_t, index_t > >::PushBackCopy().

template<typename T >

T * ot::Destruct	(	T *	array,
		size_t	elems = `1`
	)			`[inline]`

Equivalent to mem::Destruct, but exploits properties of shallow types.

Definition at line 1931 of file otrav.h.

References mem::DebugPoison().

Referenced by ArrayList< std::pair< index_t, index_t > >::Clear(), ArrayList< std::pair< index_t, index_t > >::PopBack(), ArrayList< std::pair< index_t, index_t > >::Remove(), and ArrayList< std::pair< index_t, index_t > >::ShrinkTo().

template<typename T >

size_t ot::Freeze	(	char *	block,
		const T &	src
	)			`[inline]`

Copy an object's contents into flat buffer for easy transport, normalizing pointers to offsets into the buffer for fast reuse.

Freezing is the prefered method for transmitting objects from machine to machine, storing them in temporary files, and other situations where speed is favored over efficient use of space. The primary advantage over rote serialization is that ot::SemiThaw permits (formerly) frozen objects to be used in-place. There is no need to allocate memory separately from the buffer holding the semi-thawed copy, and ot::SemiFreeze can quickly repackage the object for subsequent transmittion.

Example (sending an object):

   MyClass my_obj;
   ... // Initialize my_obj
   char *buf = mem::Alloc<char>(ot::FrozenSize(my_obj));
   ot::Freeze(buf, my_obj);
   ... // Transmit over the network
   mem::Free(buf);

Example (receiving an object):

   char *buf;
   ... // Fill buf from network
   MyClass *thawed_obj = ot::SemiThaw(buf);
   ... // Use thawed_obj
   ot::SemiDestruct(thawed_obj);
   mem::Free(buf);

To be more specific, ot::Freeze forms frozen objects by bit-copying the data structure into a flat (e.g. contiguous) buffer. Traversed pointers and arrays are processed depth-first and normalized to the bit-offsets of their represented regions from the beginning of the buffer. It is always safe to bit-copy frozen objects to new locations and their containing buffers may be freed without additional memory maintenance.

Afterward, ot::SemiThaw converts a frozen object into a semi-object by adding the buffer's memory location to all contained pointers and reconstructing transients. These are fully operational up to the ability to allocate or free non-transient fields. It is possible to bit-copy semi-objects to new locations, but after having done so, one must call either ot::Relocate or ot::SemiCopy, the former simply updating pointer positions (semantically invalidating the old location) and the latter reconstructing transients as well (leaving the old location valid). Alternately, you may call ot::SemiFreeze to revert the copy to a frozen state. Semi-objects must be explicitly destructed via ot::SemiDestruct, or may be frozen in-place with ot::SemiFreezeDestruct.

You can form a normal object directly from a frozen object with ot::InitThaw. Keep in mind that ot::InitCopy works when copying from a semi-object.

Parameters:

	block	the memory location to receive the frozen copy
	src	the object to be frozen

Returns:: the size of the object in bytes after freezing

See also:: FrozenSize, InitThaw, Relocate, SemiFreeze, SemiCopy, SemiThaw, SemiDestruct, SemiFreezeDestruct, OT_FREEZE_METHODS, Serialize, OBJECT_TRAVERSAL

Definition at line 1699 of file otrav.h.

Referenced by PointerFreeze(), and OrthoRangeSearch< T >::SaveTree().

template<typename T >

size_t ot::FrozenSize ( const T & obj ) [inline]

Determine the buffer size needed to store a frozen copy of an object.

Parameters:

obj

the object whose frozen size should be computed

Returns:: the size of the object in bytes after freezing

See also:: Freeze, OBJECT_TRAVERSAL

Definition at line 1626 of file otrav.h.

Referenced by PointerFrozenSize(), and OrthoRangeSearch< T >::SaveTree().

template<typename T >

void ot::InitCopy	(	T *	dest,
		const T &	src
	)			`[inline]`

Copy an object into a specified destination.

This function works for primitive types and untraversed types with copy constructors by calling their copy construstors. For traversed types, copying behaves identically to the copy constructor if it exists, but no copy constructor is required.

This function does not allocate memory for the top level of the copied object, permitting you to copy objects onto the stack or into your own allocated buffers.

Parameters:

	dest	an uninitialized object to receive the copy
	src	the object to be copied

See also:: OBJECT_TRAVERSAL, OT_CONSTRUCT_TRANSIENTS

Definition at line 1609 of file otrav.h.

Referenced by DBallBound< TMetric, TPoint >::CalculateMidpoint(), and Copy().

template<typename T >

size_t ot::InitDeserialize	(	T *	dest,
		FILE *	stream
	)			`[inline]`

Read a serialized version of an object from a file stream, reconstructing its transients.

Example (reading an object from file):

   MyClass my_obj;
   FILE *f_in = fopen("in.dat", "rb");
   ot::Deserialize(&my_obj, f_in);
   fclose(f_in);

Parameters:

	dest	an uninitialized object to receive the copy
	stream	a file stream openned for binary input

Returns:: number of bytes read from the stream

See also:: Serialize, SerialSize, Freeze, OBJECT_TRAVERSAL

Definition at line 1905 of file otrav.h.

template<typename T >

void ot::InitThaw	(	T *	dest,
		const char *	block
	)			`[inline]`

Copy from a frozen object into a specified destination.

Has the same effect as ot::SemiThaw followed by ot::InitCopy.

Parameters:

	dest	an uninitialized object to receive the copy
	block	the frozen object to be copied

See also:: Freeze, SemiThaw, InitCopy, OBJECT_TRAVERSAL

Definition at line 1715 of file otrav.h.

template<typename T >

COMPILER_DEPRECATED void ot::PointerFreeze	(	const T &	obj,
		char *	block
	)			`[inline]`

Renamed Freeze.

Definition at line 1987 of file otrav.h.

References Freeze().

template<typename T >

COMPILER_DEPRECATED size_t ot::PointerFrozenSize ( const T & obj ) [inline]

Renamed FrozenSize.

Definition at line 1980 of file otrav.h.

References FrozenSize().

template<typename T >

COMPILER_DEPRECATED void ot::PointerRefreeze	(	const T *	src,
		char *	dest
	)			`[inline]`

Renamed SemiFreeze.

Definition at line 1994 of file otrav.h.

References SemiFreeze().

template<typename T >

COMPILER_DEPRECATED void ot::PointerRelocate	(	const char *	old_loc,
		char *	new_loc
	)			`[inline]`

Behavior similar to SemiCopy; beware memory leaks.

Definition at line 2008 of file otrav.h.

template<typename T >

COMPILER_DEPRECATED T * ot::PointerThaw ( char * block ) [inline]

Renamed SemiThaw.

Definition at line 2001 of file otrav.h.

template<typename T >

const char * ot::Print	(	const T &	obj,
		const char *	name,
		FILE *	stream = `stdout`
	)			`[inline]`

Pretty-print an object using the standard print format.

Example (debug message):

   DEBUG_ASSERT_MSG(node.parent_ != NULL, "NULL parent (see %s).",
       ot::Print(node, "faulty_node", stderr));

Parameters:

	obj	the object to be printed
	name	the printed name attributed to the object
	stream	the output stream

Returns:: name, permitting reference, for instance, within printf

See also:: OBJECT_TRAVERSAL, OT_CUSTOM_PRINT

Definition at line 1581 of file otrav.h.

template<typename TPrintFormat , typename T >

const char * ot::Print	(	const T &	obj,
		const char *	name,
		FILE *	stream = `stdout`
	)			`[inline]`

Pretty-print an object using a given print format.

Print formats are classes used by the traversal printer to emit objects in different ways. At current, two print formats are offered: ot::StandardFormat and ot::XMLFormat.

You can define your own print format; it's interface must include:

A constructor that accepts a FILE *stream.
A templated function Untraversed(const T &obj)
For each base type, templated/overloaded functions Primitive(const char *name, index_t index, const char *type, T val)
A templated Primitive function that works on pointers
A templated function Open(const char *name, index_t index, const char *type, const T &obj, index_t len = -1)
A templated function Close(const char *name, const T &obj)

The Untraversed and Primitive functions are responsible for printing their respective types. Open and Close are called before and after traversing the contents of objects, pointers, and arrays. Only allocated arrays will have nonnegative lengths, and unallocated (NULL) arrays and pointers are handled by Primitive. See FOR_ALL_PRIMITIVES_DO to define many Primitive functions with a single macro.

Parameters:

	obj	the object to be printed
	name	the printed name attributed to the object
	stream	the output stream

Returns:: name, permitting reference, for instance, within printf

See also:: OBJECT_TRAVERSAL, OT_CUSTOM_PRINT

Definition at line 1555 of file otrav.h.

template<typename T >

T * ot::RepeatConstruct	(	T *	array,
		const T &	init,
		size_t	elems
	)			`[inline]`

Equivalent to mem::RepeatConstruct, but does not require a copy constructor to be defined for traversed types.

Note the absense of DEBUG_INIT_OK. This ensures that this function works on arrays of unconstructed objects.

Definition at line 1961 of file otrav.h.

Referenced by ArrayList< std::pair< index_t, index_t > >::InitRepeat().

template<typename T >

T * ot::SemiCopy	(	char *	block,
		const T *	orig
	)			`[inline]`

Fixes the pointers and reconstructs transients of a semi-object assuming it has already been bit-copied into a new location.

It is OK for the original location to have already been freed.

Parameters:

	block	the new location of the semi-object to freeze
	orig	the original location of the semi-object

Returns:: block recast to a T pointer

See also:: Freeze, SemiThaw, Relocate, SemiFreeze

Definition at line 1736 of file otrav.h.

Referenced by SemiThaw().

template<typename T >

void ot::SemiDestruct ( T * obj ) [inline]

Destructs a semi-object's transients and debug-poisons its memory.

Parameters:

obj

the semi-object to destroy

See also:: Freeze, SemiFreezeDestruct

Definition at line 1809 of file otrav.h.

template<typename T >

void ot::SemiFreeze	(	char *	block,
		const T *	orig
	)			`[inline]`

Re-freezes a semi-object assuming it has already been bit-copied into a new location.

Example (freezing a semi-object):

   MyClass *semi_obj;
   char *freeze_buf;
   ... // Fill semi_obj with a semi-object of size bytes
   freeze_buf = mem::AllocCopyBytes<char>(semi_obj, bytes);
   ot::SemiFreeze(freeze_buf, semi_obj);
   ...
   ot::SemiDestruct(semi_obj);

You should not use this freeze semi-objects in place because this precludes properly destructing their transients. Instead, bit-copy the semi-object to a new location and freeze it there, or use ot::SemiFreezeDestruct. It is OK for the original location to have already been freed.

Parameters:

	block	the new location of the semi-object to freeze
	orig	the original location of the semi-object

See also:: Freeze, SemiFreezeDestruct, Relocate, SemiCopy

Definition at line 1774 of file otrav.h.

Referenced by PointerRefreeze().

template<typename T >

char * ot::SemiFreezeDestruct ( T * obj ) [inline]

Re-freezes a semi-object and destructs its transients.

Parameters:

obj

the semi-object to re-freeze

Returns:: obj recast to a char pointer

See also:: Freeze, SemiDestruct, SemiFreeze

Definition at line 1826 of file otrav.h.

template<typename T >

T * ot::SemiThaw ( char * block ) [inline]

Thaws a frozen object by fixing pointers and reconstructing transients.

Equivalent to ot::SemiCopy with orig equal to NULL.

Parameters:

block

the frozen object to be thawed

Returns:: block recast to a T pointer

See also:: Freeze, SemiFreeze

Definition at line 1796 of file otrav.h.

References SemiCopy().

template<typename T >

size_t ot::Serialize	(	const T &	obj,
		FILE *	stream
	)			`[inline]`

Write a serialized version of an object to a file stream.

Serialization is more compact than freezing because it emits an object's members without the padding. Further, it emits bools to indicate whether or not a pointer is NULL (or nothing at all if the pointer is not nullable), inferring the position of the pointer's contents by depth-first traversal. This violates the alignment and stride constraints of various platforms, and thus serialization is only available in the form of writing to and reading from a file stream.

Example (saving an object to file):

   MyClass my_obj;
   ... // Initialize my_obj
   FILE *f_out = fopen("out.dat", "wb");
   ot::Serialize(my_obj, f_out);
   fclose(f_out);

Parameters:

	obj	the object to serialize
	stream	a file stream openned for binary output

Returns:: number of bytes written to the stream

See also:: Deserialize, SerialSize, Freeze, OBJECT_TRAVERSAL

Definition at line 1881 of file otrav.h.

template<typename T >

size_t ot::SerialSize ( const T & obj ) [inline]

Determine the length in bytes of a serialized version of an object.

Parameters:

obj

the object whose serial size should be computed

Returns:: the size of the object in bytes after serialization

See also:: Serialize, Deserialize, OBJECT_TRAVERSAL

Definition at line 1848 of file otrav.h.

ot Namespace Reference

Functions

Detailed Description

Function Documentation