blob: 0274812370a99f13b72ed060d5534fa6a298171a (
plain)
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
|
# Memory
Managing {{i:memory}} and {{i:allocations}} is something that every C program has to deal with.
In the case of _NNG_, it can be more complicated because the underlying platform
code can provide different allocators that might not be compatible with the use
system allocator used by `malloc` and `free`.
## Allocate Memory
```c
void *nng_alloc(size_t size);
```
The {{i:`nng_alloc`}} function allocates a contiguous memory region of
at least _size_ bytes, and returns a pointer to it.
The memory will be 64-bit aligned.
Note that the memory may have random data in it, just like with `malloc`.
If memory cannot be allocated for any reason, then `NULL` will be returned.
Applications that experience this should treat this like `NNG_ENOMEM`.
Memory returned by `nng_alloc` can be used to hold message buffers, in which
case it can be directly passed to [`nng_send`][nng_send] using the flag `NNG_FLAG_ALLOC`.
Alternatively, it can be freed when no longer needed using [`nng_free`][nng_free].
> [!IMPORTANT]
> Do not use the system `free` function (or the C++ `delete` operator) to release this memory.
> On some configurations this may work, but on others it will lead to a crash or
> other unpredictable behavior.
## Deallocate Memory
```c
void nng_free(void *ptr, size_t size);
```
The {{i:`nng_free`}} function deallocates memory previously allocated by [`nng_alloc`][nng_alloc].
The _size_ argument must exactly match the _size_ argument that was supplied to
`nng_alloc` when the memory was allocated.
## Duplicate String
```c
char *nng_strdup(const char *src);
```
The {{i:`nng_strdup`}} duplicates the string _src_ and returns it.
This is logically equivalent to using [`nng_alloc`][nng_alloc]
to allocate a region of memory of `[c] strlen(s) + 1` bytes, and then
using `strcpy` to copy the string into the destination before
returning it.
The returned string should be deallocated with
[`nng_strfree`][nng_strfree], or may be deallocated using the
[`nng_free`][nng_free] using the length of the returned string plus
one (for the `NUL` terminating byte).
## Free String
```c
void nng_strfree(char *str);
```
The {{i:`nng_strfree`}} function is a convenience function that
can be used to deallocate strings allocated with [`nng_strdup`][nng_strdup].
It is effectively the same as `[c] nng_free(strlen(str) + 1)`.
[nng_alloc]: #allocate-memory
[nng_free]: #deallocate-memory
[nng_strdup]: #duplicate-string
[nng_strfree]: #free-string
[nng_send]: TODO.md
|
