From 45ac4fa56b6e5c31a28fd08eaad14a09bf3934f6 Mon Sep 17 00:00:00 2001 From: gdamore Date: Sun, 27 Oct 2024 18:55:51 +0000 Subject: deploy: ffeb31c64ea72c4eb287f75b641ca2a707df90b0 --- ref/api/memory.html | 351 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 351 insertions(+) create mode 100644 ref/api/memory.html (limited to 'ref/api/memory.html') diff --git a/ref/api/memory.html b/ref/api/memory.html new file mode 100644 index 00000000..3d58726f --- /dev/null +++ b/ref/api/memory.html @@ -0,0 +1,351 @@ + + + + + + Memory - NNG Reference Manual (DRAFT) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Memory

+

Managing memory and 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

+
void *nng_alloc(size_t size);
+
+

The 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 using the flag NNG_FLAG_ALLOC. +Alternatively, it can be freed when no longer needed using 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

+
void nng_free(void *ptr, size_t size);
+
+

The nng_free function deallocates memory previously allocated by nng_alloc.

+

The size argument must exactly match the size argument that was supplied to +nng_alloc when the memory was allocated.

+

Duplicate String

+
char *nng_strdup(const char *src);
+
+

The nng_strdup duplicates the string src and returns it.

+

This is logically equivalent to using nng_alloc +to allocate a region of memory of 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, or may be deallocated using the +nng_free using the length of the returned string plus +one (for the NUL terminating byte).

+

Free String

+
void nng_strfree(char *str);
+
+

The nng_strfree function is a convenience function that +can be used to deallocate strings allocated with nng_strdup.

+

It is effectively the same as nng_free(strlen(str) + 1).

+ + + + + + +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + -- cgit v1.2.3-70-g09d2