| 1 |
pippijn |
1.1 |
=head1 Heap allocation |
| 2 |
|
|
|
| 3 |
|
|
Within Ermyth, most larger structures are allocated by a custom |
| 4 |
|
|
L<block allocator|balloc.html> but sometimes, you don't want that. This is |
| 5 |
|
|
the case for char arrays for instance. The block allocator doesn't work |
| 6 |
|
|
for char arrays and it makes little sense to use it for that. Just using |
| 7 |
|
|
the bare system malloc is error prone as you have to take care of segment |
| 8 |
|
|
sizes and things like that. C++ provides templates, so why not use them? |
| 9 |
|
|
|
| 10 |
|
|
=head2 Allocation functions |
| 11 |
|
|
|
| 12 |
|
|
Ermyth provides several allocation functions with different semantics. All |
| 13 |
|
|
allocation routines may throw std::bad_alloc. The deallocation routine sfree |
| 14 |
|
|
does not throw any exceptions. |
| 15 |
|
|
|
| 16 |
|
|
=over |
| 17 |
|
|
|
| 18 |
|
|
=item template<typename T> T *alloc (int n = 1) |
| 19 |
|
|
|
| 20 |
|
|
Example: C<< char *str = alloc<char> (20) >> allocates a char array of size |
| 21 |
|
|
20 * sizeof (char). |
| 22 |
|
|
|
| 23 |
|
|
=item template<typename T> T *alloc (unsigned n, T *src) |
| 24 |
|
|
|
| 25 |
|
|
Example: C<< char *newstr = alloc (strlen (str), str) >> basically emulates |
| 26 |
|
|
strdup (). |
| 27 |
|
|
|
| 28 |
|
|
=item template<typename T> T *alloc (unsigned n, T *src, size_t len) |
| 29 |
|
|
|
| 30 |
|
|
Safe and slow version of above: never tries to copy more than len from src. |
| 31 |
|
|
|
| 32 |
|
|
=item template<typename T> T *alloc (unsigned n, char c) |
| 33 |
|
|
|
| 34 |
|
|
Example: C<< char *newstr = alloc<char> (20, 0) >> allocates a char array of |
| 35 |
|
|
size 20 * sizeof (char) and initialises that memory to zero. |
| 36 |
|
|
|
| 37 |
|
|
=item template<typename T> void sfree (T *ptr) |
| 38 |
|
|
|
| 39 |
|
|
Frees memory used by ptr. Works just like free (). |
| 40 |
|
|
|
| 41 |
|
|
=back |
| 42 |
|
|
|
| 43 |
|
|
Furthermore, Ermyth provides two convenience functions that use the above |
| 44 |
|
|
memory functions and therefore require the use of sfree (). |
| 45 |
|
|
|
| 46 |
|
|
=over |
| 47 |
|
|
|
| 48 |
|
|
=item char *sstrdup (char const * const s) |
| 49 |
|
|
|
| 50 |
|
|
Returns a duplicate of the passed string. Emulates standard C strdup. |
| 51 |
|
|
|
| 52 |
|
|
=item char *sstrndup (char const * const s, int len) |
| 53 |
|
|
|
| 54 |
|
|
The same as strndup but with the above memory functions. |
| 55 |
|
|
|
| 56 |
|
|
=item template<size_t N> char *sstrndup (char const (&s)[N]) |
| 57 |
|
|
|
| 58 |
|
|
Takes away the need of counting characters if you want to duplicate |
| 59 |
|
|
a string literal. |
| 60 |
|
|
|
| 61 |
|
|
=back |
| 62 |
|
|
|
| 63 |
|
|
|
| 64 |
|
|
=head2 Other allocators |
| 65 |
|
|
|
| 66 |
|
|
Ermyth provides other allocators aside from the L<block allocator|balloc.html>. |
| 67 |
|
|
One of these is the C<zero_initialised> allocator. It is used just like the |
| 68 |
|
|
block allocator. |
| 69 |
|
|
|
| 70 |
|
|
struct mystruct : zero_initialised |
| 71 |
|
|
{ |
| 72 |
|
|
char mystring[30]; |
| 73 |
|
|
}; |
| 74 |
|
|
|
| 75 |
|
|
Makes sure that all objects instantiated from this class are initialised to |
| 76 |
|
|
zero. B<Important>: Do not combine allocators. |
