Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / genalloc.h / genalloc_ready_tuned.3.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
% limb manual
% genalloc_ready_tuned(3)
% limb 0.1.0
% 2023-07-24

# NAME

genalloc_ready_tuned, genalloc_ready, genalloc_readyplus, genalloc_free,
genalloc_deepfree, genalloc_deepfree_size, genalloc_shrink - allocate and
free memory associated with a genalloc

# SYNOPSIS

    #include <limb/genalloc.h>

```pre hl
int genalloc_ready_tuned(<em>type</em>, genalloc *<em>ga</em>, int <em>num</em>, size_t <em>base</em>, size_t <em>a</em>, size_t <em>b</em>)
int genalloc_ready(<em>type</em>, genalloc *<em>ga</em>, int <em>num</em>)
int genalloc_readyplus(<em>type</em>, genalloc *<em>ga</em>, int <em>num</em>)

int genalloc_shrink(<em>type</em>, genalloc *<em>ga</em>)

void genalloc_free(<em>type</em>, genalloc *<em>ga</em>)
void genalloc_deepfree(<em>type</em>, genalloc *<em>ga</em>, free_func *<em>fn</em>)
void genalloc_deepfree_size(genalloc *<em>ga</em>, free_func *<em>fn</em>, size_t <em>len</em>)
```

# DESCRIPTION

The `genalloc_ready`() macro ensure that genalloc pointed by `ga` has enough
memory for `num` elements of type `type`, reallocating memory if needed.
This does not mean as much is available, as there might be data in use already.

The `genalloc_readyplus`() macro ensure that genalloc pointed by `ga` has enough
memory available for `num` more elements of type `type`, reallocating memory if
needed. Available here means space that is allocated but not yet in use, making
this the most commonly used way to prepare a *genalloc* before writing data into
it.

The `genalloc_ready_tuned`() is similar to `genalloc_ready`() but with more
fine-tuning settings.

Note that this is only needed when writing into the *genalloc* directly, as all
functions of the *genalloc* API (e.g. [genalloc_append](3)) handles that
automatically.

The `genalloc_shrink`() macro will ensure that the allocated memory is only
as large as is in use in genalloc `ga`.

The `genalloc_deepfree_size`() function is useful when storing pointers in a
genalloc, or any data that must have associated memory freed for each elements.
It will iterate over the data in genalloc `ga` - which must contain elements of
`len` bytes - and call the function `fn` with the address of each element as
argument.
Once done, it will free all memory associated with the genalloc `ga` itself.

The `genalloc_deepfree`() macro is similar to `genalloc_deepfree_size`() but for
genalloc containing elements of type `type`.

The `genalloc_free`() macro will free all memory associated with the genalloc
`ga`.

# RETURN VALUE

These functions (except for `genalloc_free`(), `genalloc_deepfree`() and
`genalloc_deepfree_size`()) return 1 on success. Otherwise they return 0 and
set `errno` to indicate the error.

# ERRORS

The `genalloc_ready_tuned`(), `genalloc_ready`() and `genalloc_readyplus`()
functions may fail for the errors described for [stralloc_ready_tuned](3),
[stralloc_ready](3) and [stralloc_readyplus](3), respectively.

The `genalloc_shrink`() function may fail for the errors described for
[stralloc_shrink](3).

# SEE ALSO

[genalloc_remove](3)