Memory Allocation

Detailed Description

Tidy can use a user-provided allocator for all memory allocations.

If this allocator is not provided, then a default allocator is used which simply wraps standard C malloc()/free() calls. These wrappers call the panic() function upon any failure. The default panic function prints an out of memory message to stderr, and calls exit(2).

For applications in which it is unacceptable to abort in the case of memory allocation, then the panic function can be replaced with one which longjmps() out of the LibTidy code. For this to clean up completely, you should be careful not to use any Tidy methods that open files as these will not be closed before panic() is called.

Calling the xxxWithAllocator() family (tidyCreateWithAllocator, tidyBufInitWithAllocator, tidyBufAllocWithAllocator) allow setting custom allocators.

All parts of the document use the same allocator. Calls that require a user-provided buffer can optionally use a different allocator.

For reference in designing a plug-in allocator, most allocations made by LibTidy are less than 100 bytes, corresponding to attribute names and values, etc.

There is also an additional class of much larger allocations which are where most of the data from the lexer is stored. It is not currently possible to use a separate allocator for the lexer; this would be a useful extension.

In general, approximately 1/3rd of the memory used by LibTidy is freed during the parse, so if memory usage is an issue then an allocator that can reuse this memory is a good idea.

To create your own allocator, do something like the following:

typedef struct _MyAllocator {
   TidyAllocator base;
   // ...other custom allocator state...
} MyAllocator;
 
void* MyAllocator_alloc(TidyAllocator *base, void *block, size_t nBytes) {
    MyAllocator *self = (MyAllocator*)base;
    // ...
}
// etc.
 
static const TidyAllocatorVtbl MyAllocatorVtbl = {
    MyAllocator_alloc,
    MyAllocator_realloc,
    MyAllocator_free,
    MyAllocator_panic
};
 
myAllocator allocator;
TidyDoc doc;
 
allocator.base.vtbl = &MyAllocatorVtbl;
//...initialise allocator specific state...
doc = tidyCreateWithAllocator(&allocator);

Although this looks slightly long-winded, the advantage is that to create a custom allocator you simply need to set the vtbl pointer correctly. The vtbl itself can reside in static/global data, and hence does not need to be initialised each time an allocator is created, and furthermore the memory is shared amongst all created allocators.

Data Structures
struct	TidyAllocator
	Tidy's built-in default allocator. More...
struct	TidyAllocatorVtbl
	This structure is the function table for an allocator. More...

Typedefs
typedef void(TIDY_CALL *	TidyFree) (void *buf)
	Callback for free replacement. More...
typedef void *(TIDY_CALL *	TidyMalloc) (size_t len)
	Callback for malloc replacement. More...
typedef void(TIDY_CALL *	TidyPanic) (ctmbstr mssg)
	Callback for out of memory panic state. More...
typedef void *(TIDY_CALL *	TidyRealloc) (void *buf, size_t len)
	Callback for realloc replacement. More...

Functions
Bool TIDY_CALL	tidySetFreeCall (TidyFree ffree)
	Give Tidy a free() replacement. More...
Bool TIDY_CALL	tidySetMallocCall (TidyMalloc fmalloc)
	Give Tidy a malloc() replacement. More...
Bool TIDY_CALL	tidySetPanicCall (TidyPanic fpanic)
	Give Tidy an "out of memory" handler. More...
Bool TIDY_CALL	tidySetReallocCall (TidyRealloc frealloc)
	Give Tidy a realloc() replacement. More...

---

Data Structure Documentation

_TidyAllocator

struct _TidyAllocator

Tidy's built-in default allocator.

Data Fields
const TidyAllocatorVtbl *	vtbl	The allocator's function table.

_TidyAllocatorVtbl

struct _TidyAllocatorVtbl

This structure is the function table for an allocator.

Note that all functions in this table must be provided.

Public Member Functions
void **	alloc (TidyAllocator *self, size_t nBytes)
	Called to allocate a block of nBytes of memory. More...
void *	free (TidyAllocator *self, void *block)
	Called to free a previously allocated block of memory. More...
void *	panic (TidyAllocator *self, ctmbstr msg)
	Called when a panic condition is detected. More...
void **	realloc (TidyAllocator *self, void *block, size_t nBytes)
	Called to resize (grow, in general) a block of memory. More...

Member Function Documentation

alloc()

void* * alloc	(	TidyAllocator *	self,
		size_t	nBytes
	)

Called to allocate a block of nBytes of memory.

Parameters

self	The TidyAllocator to use to alloc memory.
nBytes	The number of bytes to allocate.

free()

void* free	(	TidyAllocator *	self,
		void *	block
	)

Called to free a previously allocated block of memory.

Parameters

self	The TidyAllocator to use to free memory.
block	The block to free.

panic()

void* panic	(	TidyAllocator *	self,
		ctmbstr	msg
	)

Called when a panic condition is detected.

Must support block == NULL. This function is not called if either alloc() or realloc() fails; it is up to the allocator to do this. Currently this function can only be called if an error is detected in the tree integrity via the internal function CheckNodeIntegrity(). This is a situation that can only arise in the case of a programming error in LibTidy. You can turn off node integrity checking by defining the constant NO_NODE_INTEGRITY_CHECK during the build.

Parameters

self	The TidyAllocator to use to panic.
msg	The panic message.

realloc()

void* * realloc	(	TidyAllocator *	self,
		void *	block,
		size_t	nBytes
	)

Called to resize (grow, in general) a block of memory.

Must support being called with NULL.

Parameters

self	The TidyAllocator to use to realloc memory.
block	The pointer to the existing block.
nBytes	The number of bytes to allocate.

Typedef Documentation

TidyFree

typedef void(TIDY_CALL * TidyFree) (void *buf)

Callback for free replacement.

TidyMalloc

typedef void*(TIDY_CALL * TidyMalloc) (size_t len)

Callback for malloc replacement.

TidyPanic

typedef void(TIDY_CALL * TidyPanic) (ctmbstr mssg)

Callback for out of memory panic state.

TidyRealloc

typedef void*(TIDY_CALL * TidyRealloc) (void *buf, size_t len)

Callback for realloc replacement.

Function Documentation

tidySetFreeCall()

Bool TIDY_CALL tidySetFreeCall

(

TidyFree

ffree

)

Give Tidy a free() replacement.

tidySetMallocCall()

Bool TIDY_CALL tidySetMallocCall

(

TidyMalloc

fmalloc

)

Give Tidy a malloc() replacement.

tidySetPanicCall()

Bool TIDY_CALL tidySetPanicCall

(

TidyPanic

fpanic

)

Give Tidy an "out of memory" handler.

tidySetReallocCall()

Bool TIDY_CALL tidySetReallocCall

(

TidyRealloc

frealloc

)

Give Tidy a realloc() replacement.