107
107
typedef struct _TidyBuffer TidyBuffer;
110
/** @defgroup Memory Memory Allocation
112
** Tidy uses a user provided allocator for all
113
** memory allocations. If this allocator is
114
** not provided, then a default allocator is
115
** used which simply wraps standard C malloc/free
116
** calls. These wrappers call the panic function
117
** upon any failure. The default panic function
118
** prints an out of memory message to stderr, and
121
** For applications in which it is unacceptable to
122
** abort in the case of memory allocation, then the
123
** panic function can be replaced with one which
124
** longjmps() out of the tidy code. For this to
125
** clean up completely, you should be careful not
126
** to use any tidy methods that open files as these
127
** will not be closed before panic() is called.
129
** TODO: associate file handles with tidyDoc and
130
** ensure that tidyDocRelease() can close them all.
132
** Calling the withAllocator() family (
133
** tidyCreateWithAllocator, tidyBufInitWithAllocator,
134
** tidyBufAllocWithAllocator) allow settings custom
137
** All parts of the document use the same allocator.
138
** Calls that require a user provided buffer can
139
** optionally use a different allocator.
141
** For reference in designing a plug-in allocator,
142
** most allocations made by tidy are less than 100
143
** bytes, corresponding to attribute names/values, etc.
145
** There is also an additional class of much larger
146
** allocations which are where most of the data from
147
** the lexer is stored. (It is not currently possible
148
** to use a separate allocator for the lexer, this
149
** would be a useful extension).
151
** In general, approximately 1/3rd of the memory
152
** used by tidy is freed during the parse, so if
153
** memory usage is an issue then an allocator that
154
** can reuse this memory is a good idea.
159
/** Prototype for the allocator's function table */
160
struct _TidyAllocatorVtbl;
161
/** The allocators function table */
162
typedef struct _TidyAllocatorVtbl TidyAllocatorVtbl;
164
/** Prototype for the allocator */
165
struct _TidyAllocator;
166
/** The allocator **/
167
typedef struct _TidyAllocator TidyAllocator;
169
/** An allocator's function table. All functions here must
172
struct _TidyAllocatorVtbl {
173
/** Called to allocate a block of nBytes of memory */
174
void* (TIDY_CALL *alloc)( TidyAllocator *self, size_t nBytes );
175
/** Called to resize (grow, in general) a block of memory.
176
Must support being called with NULL.
178
void* (TIDY_CALL *realloc)( TidyAllocator *self, void *block, size_t nBytes );
179
/** Called to free a previously allocated block of memory */
180
void (TIDY_CALL *free)( TidyAllocator *self, void *block);
181
/** Called when a panic condition is detected. Must support
182
block == NULL. This function is not called if either alloc
183
or realloc fails; it is up to the allocator to do this.
184
Currently this function can only be called if an error is
185
detected in the tree integrity via the internal function
186
CheckNodeIntegrity(). This is a situation that can
187
only arise in the case of a programming error in tidylib.
188
You can turn off node integrity checking by defining
189
the constant NO_NODE_INTEGRITY_CHECK during the build.
191
void (TIDY_CALL *panic)( TidyAllocator *self, ctmbstr msg );
194
/** An allocator. To create your own allocator, do something like
197
typedef struct _MyAllocator {
199
...other custom allocator state...
202
void* MyAllocator_alloc(TidyAllocator *base, void *block, size_t nBytes)
204
MyAllocator *self = (MyAllocator*)base;
209
static const TidyAllocatorVtbl MyAllocatorVtbl = {
216
myAllocator allocator;
219
allocator.base.vtbl = &MyAllocatorVtbl;
220
...initialise allocator specific state...
221
doc = tidyCreateWithAllocator(&allocator);
224
Although this looks slightly long winded, the advantage is that to create
225
a custom allocator you simply need to set the vtbl pointer correctly.
226
The vtbl itself can reside in static/global data, and hence does not
227
need to be initialised each time an allocator is created, and furthermore
228
the memory is shared amongst all created allocators.
230
struct _TidyAllocator {
231
const TidyAllocatorVtbl *vtbl;
234
/** Callback for "malloc" replacement */
235
typedef void* (TIDY_CALL *TidyMalloc)( size_t len );
236
/** Callback for "realloc" replacement */
237
typedef void* (TIDY_CALL *TidyRealloc)( void* buf, size_t len );
238
/** Callback for "free" replacement */
239
typedef void (TIDY_CALL *TidyFree)( void* buf );
240
/** Callback for "out of memory" panic state */
241
typedef void (TIDY_CALL *TidyPanic)( ctmbstr mssg );
244
/** Give Tidy a malloc() replacement */
245
TIDY_EXPORT Bool TIDY_CALL tidySetMallocCall( TidyMalloc fmalloc );
246
/** Give Tidy a realloc() replacement */
247
TIDY_EXPORT Bool TIDY_CALL tidySetReallocCall( TidyRealloc frealloc );
248
/** Give Tidy a free() replacement */
249
TIDY_EXPORT Bool TIDY_CALL tidySetFreeCall( TidyFree ffree );
250
/** Give Tidy an "out of memory" handler */
251
TIDY_EXPORT Bool TIDY_CALL tidySetPanicCall( TidyPanic fpanic );
253
/** @} end Memory group */
110
255
/** @defgroup Basic Basic Operations
112
257
** Tidy public interface
491
639
/** @} end IO group */
494
/** @defgroup Memory Memory Allocation
496
** By default, Tidy will use its own wrappers
497
** around standard C malloc/free calls.
498
** These wrappers will abort upon any failures.
499
** If any are set, all must be set.
500
** Pass NULL to clear previous setting.
502
** May be used to set environment-specific allocators
503
** such as used by web server plugins, etc.
508
/** Callback for "malloc" replacement */
509
typedef void* (TIDY_CALL *TidyMalloc)( size_t len );
510
/** Callback for "realloc" replacement */
511
typedef void* (TIDY_CALL *TidyRealloc)( void* buf, size_t len );
512
/** Callback for "free" replacement */
513
typedef void (TIDY_CALL *TidyFree)( void* buf );
514
/** Callback for "out of memory" panic state */
515
typedef void (TIDY_CALL *TidyPanic)( ctmbstr mssg );
517
/** Give Tidy a malloc() replacement */
518
TIDY_EXPORT Bool TIDY_CALL tidySetMallocCall( TidyMalloc fmalloc );
519
/** Give Tidy a realloc() replacement */
520
TIDY_EXPORT Bool TIDY_CALL tidySetReallocCall( TidyRealloc frealloc );
521
/** Give Tidy a free() replacement */
522
TIDY_EXPORT Bool TIDY_CALL tidySetFreeCall( TidyFree ffree );
523
/** Give Tidy an "out of memory" handler */
524
TIDY_EXPORT Bool TIDY_CALL tidySetPanicCall( TidyPanic fpanic );
526
/** @} end Memory group */
528
641
/* TODO: Catalog all messages for easy translation
529
642
TIDY_EXPORT ctmbstr tidyLookupMessage( int errorNo );
added
removed
include/tidy.h
