template<class Ch = char>
class rapidxml::memory_pool< Ch >
This class is used by the parser to create new nodes and attributes, without overheads of dynamic memory allocation. In most cases, you will not need to use this class directly. However, if you need to create nodes manually or modify names/values of nodes, you are encouraged to use memory_pool of relevant xml_document to allocate the memory. Not only is this faster than allocating them by using new operator, but also their lifetime will be tied to the lifetime of document, possibly simplyfing memory management.
Call allocate_node() or allocate_attribute() functions to obtain new nodes or attributes from the pool. You can also call allocate_string() function to allocate strings. Such strings can then be used as names or values of nodes without worrying about their lifetime. Note that there is no free() function – all allocations are freed at once when clear() function is called, or when the pool is destroyed.
It is also possible to create a standalone memory_pool, and use it to allocate nodes, whose lifetime will not be tied to any document.
Pool maintains RAPIDXML_STATIC_POOL_SIZE bytes of statically allocated memory. Until static memory is exhausted, no dynamic memory allocations are done. When static memory is exhausted, pool allocates additional blocks of memory of size RAPIDXML_DYNAMIC_POOL_SIZE each, by using global new[] and delete[] operators. This behaviour can be changed by setting custom allocation routines. Use set_allocator() function to set them.
Allocations for nodes, attributes and strings are aligned at RAPIDXML_ALIGNMENT bytes. This value defaults to the size of pointer on target architecture.
To obtain absolutely top performance from the parser, it is important that all nodes are allocated from a single, contiguous block of memory. Otherwise, cache misses when jumping between two (or more) disjoint blocks of memory can slow down parsing quite considerably. If required, you can tweak RAPIDXML_STATIC_POOL_SIZE, RAPIDXML_DYNAMIC_POOL_SIZE and RAPIDXML_ALIGNMENT to obtain best wasted memory to performance compromise. To do it, define their values before rapidxml.hpp file is included.
- Parameters
-
| Ch | Character type of created nodes. |
Definition at line 379 of file rapidxml.hpp.
template<class Ch = char>
Allocates a new attribute from the pool, and optionally assigns name and value to it. If the allocation request cannot be accomodated, this function will throw std::bad_alloc. If exceptions are disabled by defining RAPIDXML_NO_EXCEPTIONS, this function will call rapidxml::parse_error_handler() function.
- Parameters
-
| name | Name to assign to the attribute, or 0 to assign no name. |
| value | Value to assign to the attribute, or 0 to assign no value. |
| name_size | Size of name to assign, or 0 to automatically calculate size from name string. |
| value_size | Size of value to assign, or 0 to automatically calculate size from value string. |
- Returns
- Pointer to allocated attribute. This pointer will never be NULL.
Definition at line 447 of file rapidxml.hpp.
template<class Ch = char>
Allocates a new node from the pool, and optionally assigns name and value to it. If the allocation request cannot be accomodated, this function will throw std::bad_alloc. If exceptions are disabled by defining RAPIDXML_NO_EXCEPTIONS, this function will call rapidxml::parse_error_handler() function.
- Parameters
-
| type | Type of node to create. |
| name | Name to assign to the node, or 0 to assign no name. |
| value | Value to assign to the node, or 0 to assign no value. |
| name_size | Size of name to assign, or 0 to automatically calculate size from name string. |
| value_size | Size of value to assign, or 0 to automatically calculate size from value string. |
- Returns
- Pointer to allocated node. This pointer will never be NULL.
Definition at line 415 of file rapidxml.hpp.
template<class Ch = char>
Allocates a char array of given size from the pool, and optionally copies a given string to it. If the allocation request cannot be accomodated, this function will throw std::bad_alloc. If exceptions are disabled by defining RAPIDXML_NO_EXCEPTIONS, this function will call rapidxml::parse_error_handler() function.
- Parameters
-
| source | String to initialize the allocated memory with, or 0 to not initialize it. |
| size | Number of characters to allocate, or zero to calculate it automatically from source string length; if size is 0, source string must be specified and null terminated. |
- Returns
- Pointer to allocated char array. This pointer will never be NULL.
Definition at line 476 of file rapidxml.hpp.
template<class Ch = char>
Sets or resets the user-defined memory allocation functions for the pool. This can only be called when no memory is allocated from the pool yet, otherwise results are undefined. Allocation function must not return invalid pointer on failure. It should either throw, stop the program, or use longjmp() function to pass control to other place of program. If it returns invalid pointer, results are undefined.
User defined allocation functions must have the following forms:
void *allocate(std::size_t size);
void free(void *pointer);
- Parameters
-
| af | Allocation function, or 0 to restore default function |
| ff | Free function, or 0 to restore default function |
Definition at line 552 of file rapidxml.hpp.
