diff options
Diffstat (limited to 'docs/reference/src/api')
33 files changed, 0 insertions, 1369 deletions
diff --git a/docs/reference/src/api/msg/index.md b/docs/reference/src/api/msg/index.md deleted file mode 100644 index 54d8d9b8..00000000 --- a/docs/reference/src/api/msg/index.md +++ /dev/null @@ -1,97 +0,0 @@ -# Messages - -Messages in Scalability Protocols are the fundamental unit of transmission -and reception, -as these protocols are fundamentally message-oriented. - -## {{i: Message object}} - -An `nng_msg` represents a single {{i:message}} sent between Scalability Protocols peers. - -Messages have a {{i:body}}, containing the application supplied -payload, and a {{i:header}}, containing protocol specific routing and similar -related information. - -> [!TIP] -> Only applications using [raw](../../overview/raw.md) mode need to -> access the message header. - -### Creating, Destroying and Using - -Messages are allocated using [`nng_msg_alloc()`](nng_msg_alloc.md), -and are deallocated using [`nng_msg_free()`](nng_msg_free.md). - -In addition there are other functions used to access message contents, -including adding data to either the beginning or end of the message, -automatic data conversion, and removing data from the beginning or end. - -### Performance Considerations - -While there are convenience wrappers for sending and receiving arrays of -bytes, using message objects directly when possible will give better -performance by reducing data copies and needless allocations. - -These functions are designed to try to avoid copying message contents -by making use of scratch areas at the beginning and end of the message. -These scratch areas, the "headroom" and "tailroom", are automatically -included when allocating a message. - -### Direct Use Forbidden - -The `nng_msg` structure is opaque, and applications should never try to -rely on the size of it, nor access internal members directly. -This insulates the application from changes in subsequent _NNG_ versions -that would affect the binary representation of the `nng_msg` itself. - -## Examples - -### Example 1: Preparing a message for use - -```c - #include <nng/nng.h> - - nng_msg *m; - if (nng_msg_alloc(&m, strlen("content") + 1) != 0) { - // handle error - } - strcpy(nng_msg_body(m), "content"); -``` - -### Example 2: Preallocating message content - -```c - if (nng_msg_alloc(&m, 1024) != 0) { - // handle error - } - while ((val64 = next_datum()) != 0) P - if (nng_msg_append_u64(m, val64) != 0) { - // handle error - } - } -``` - -## See Also - -[nng_aio_get_msg](../aio/nng_aio_get_msg.md), -[nng_aio_set_msg](../aio/nng_aio_set_msg.md), -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_dup](nng_msg_dup.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_header](nng_msg_header.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_clear](nng_msg_header_clear.md), -[nng_msg_header_insert](nng_msg_header_insert.md), -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_set_pipe](nng_msg_set_pipe.md), -[nng_msg_trim](nng_msg_trim.md), -[nng_recvmsg](../socket/nng_recvmsg.md), -[nng_sendmsg](../socket/nng_sendmsg.md) diff --git a/docs/reference/src/api/msg/nng_msg_alloc.md b/docs/reference/src/api/msg/nng_msg_alloc.md deleted file mode 100644 index 163d193b..00000000 --- a/docs/reference/src/api/msg/nng_msg_alloc.md +++ /dev/null @@ -1,40 +0,0 @@ -# nng_msg_alloc - -## NAME - -nng_msg_alloc --- allocate a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_alloc(nng_msg **msgp, size_t size); -``` - -## DESCRIPTION - -The `nng_msg_alloc()` function allocates a new message with body length _size_ -and stores the result in _msgp_. -Messages allocated with this function contain a body and optionally a header. -They are used with receive and transmit functions. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to allocate a message. - -## SEE ALSO - -[nng_msg_free](nng_msg_free.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_dup](nng_msg_dup.md), -[nng_msg_header](nng_msg_header.md), -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/msg/nng_msg_append.md b/docs/reference/src/api/msg/nng_msg_append.md deleted file mode 100644 index 5807d3a6..00000000 --- a/docs/reference/src/api/msg/nng_msg_append.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_msg_append - -## NAME - -nng_msg_append --- append to message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_append(nng_msg *msg, const void *val, size_t size); -int nng_msg_append_u16(nng_msg *msg, uint16_t val16); -int nng_msg_append_u32(nng_msg *msg, uint32_t val32); -int nng_msg_append_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_append()` family of functions appends data to -the end of the body of message _msg_, reallocating it if necessary. -The first function appends _size_ bytes, copying them from _val_. -The remaining functions append the value specified (such as _val32_) in -network-byte order (big-endian). - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_body.md b/docs/reference/src/api/msg/nng_msg_body.md deleted file mode 100644 index abd49c7f..00000000 --- a/docs/reference/src/api/msg/nng_msg_body.md +++ /dev/null @@ -1,47 +0,0 @@ -# nng_msg_body - -## NAME - -nng_msg_body --- return message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void *nng_msg_body(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_body()` function returns a pointer to the start of the body -content of the message _msg_. - -> [!NOTE] -> The value returned by this is invalidated by a call to any of the -> functions that modify the message itself. -> Such functions are -> [`nng_msg_free()`](nng_msg_free.md), -> [`nng_msg_realloc()`](nng_msg_realloc.md), -> any of the [`nng_msg_trim()`](nng_msg_trim.md), -> [`nng_msg_chop()`](nng_msg_chop.md), -> [`nng_msg_append()`](nng_msg_append.md), -> or [`nng_msg_insert()`](nng_msg_insert.md) variants. - -## RETURN VALUES - -Pointer to start of message body. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_clear](nng_msg_clear.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_capacity.md b/docs/reference/src/api/msg/nng_msg_capacity.md deleted file mode 100644 index 707a04e3..00000000 --- a/docs/reference/src/api/msg/nng_msg_capacity.md +++ /dev/null @@ -1,30 +0,0 @@ -# nng_msg_capacity - -## NAME - -nng_msg_capacity --- return message body length - -## SYNOPSIS - -```c -#include <nng/nng.h> - -size_t nng_msg_capacity(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_capacity()` returns the storage allocated for the body of message _msg_. -The capacity includes the current contents of the message and free space after it. -The message body may grow to capacity without performing any further allocations. - -## RETURN VALUES - -Allocated capacity for message body. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_reserve](nng_msg_reserve.md) -[nng_msg_body](nng_msg_body.md) diff --git a/docs/reference/src/api/msg/nng_msg_chop.md b/docs/reference/src/api/msg/nng_msg_chop.md deleted file mode 100644 index fc9a0df5..00000000 --- a/docs/reference/src/api/msg/nng_msg_chop.md +++ /dev/null @@ -1,47 +0,0 @@ -# nng_msg_chop - -## NAME - -nng_msg_chop --- remove data from end of message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_chop(nng_msg *msg, size_t size); -int nng_msg_chop_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_chop_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_chop_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_chop()` family of functions removes data from -the end of the body of message _msg_. -The first function removes _size_ bytes. -The remaining functions remove 2, 4, or 8 bytes, and stores them in the value -(such as _val32_), -after converting them from network-byte order (big-endian) to native byte order. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message body is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_clear.md b/docs/reference/src/api/msg/nng_msg_clear.md deleted file mode 100644 index af25c072..00000000 --- a/docs/reference/src/api/msg/nng_msg_clear.md +++ /dev/null @@ -1,23 +0,0 @@ -# nng_msg_clear - -## NAME - -nng_msg_clear --- clear message body content - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_clear(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_clear()` function resets the body length of _msg_ to zero. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_reserve](nng_msg_reserve.md) diff --git a/docs/reference/src/api/msg/nng_msg_dup.md b/docs/reference/src/api/msg/nng_msg_dup.md deleted file mode 100644 index dae376e8..00000000 --- a/docs/reference/src/api/msg/nng_msg_dup.md +++ /dev/null @@ -1,34 +0,0 @@ -# nng_msg_dup - -## NAME - -nng_msg_dup --- duplicate a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_dup(nng_msg **dup, nng_msg_t *orig); -``` - -## DESCRIPTION - -The `nng_msg_dup()` makes a duplicate of the original message _orig_, and -saves the result in the location pointed by _dup_. -The actual message body and header content is copied, -but the duplicate may contain a -different amount of unused space than the original message. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to duplicate a message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_free](nng_msg_free.md) diff --git a/docs/reference/src/api/msg/nng_msg_free.md b/docs/reference/src/api/msg/nng_msg_free.md deleted file mode 100644 index 94887be0..00000000 --- a/docs/reference/src/api/msg/nng_msg_free.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_msg_free - -## NAME - -nng_msg_free --- free a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_free(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_free()` function deallocates the message _msg_ entirely. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/msg/nng_msg_get_pipe.md b/docs/reference/src/api/msg/nng_msg_get_pipe.md deleted file mode 100644 index 5f935347..00000000 --- a/docs/reference/src/api/msg/nng_msg_get_pipe.md +++ /dev/null @@ -1,44 +0,0 @@ -# nng_msg_get_pipe - -## NAME - -nng_msg_get_pipe --- get pipe for message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -nng_pipe nng_msg_get_pipe(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_get_pipe()` returns the [`nng_pipe`](../conn/nng_pipe.md) object -associated with message _msg_. -On receive, this is the pipe from which a message was received. -On transmit, this would be the pipe that the message should be delivered -to, if a specific peer is required. - -> [!NOTE] -> Not all protocols support overriding the destination pipe. - -The most usual use case for this is to obtain information about the peer -from which the message was received. -This can be used to provide different behaviors for different peers, such as -a higher level of authentication for peers located on an untrusted network. -The [`nng_pipe_get()`](../conn/nng_pipe_get.md) function -is useful in this situation. - -## RETURN VALUES - -This function returns the pipe associated with this message, which will -be a positive value. -If the pipe is non-positive, then that indicates that -no specific pipe is associated with the message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_set_pipe](nng_msg_set_pipe.md), -[nng_pipe_get](../conn/nng_pipe_get.md) diff --git a/docs/reference/src/api/msg/nng_msg_header.md b/docs/reference/src/api/msg/nng_msg_header.md deleted file mode 100644 index 7a75464d..00000000 --- a/docs/reference/src/api/msg/nng_msg_header.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header - -## NAME - -nng_msg_header --- return message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void *nng_msg_header(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_header()` function returns a pointer to the start of the header -content of the message _msg_. - -> [!NOTE] -> The message header contains protocol-specific header content. Most -> applications should not need to access this content, but it is available -> for [raw](../../overview/raw.md) mode sockets. - -> [!NOTE] -> The value returned by this is invalidated by a call to any of the -> functions that modify the message or the header content. - -## RETURN VALUES - -Pointer to start of message header. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_append.md b/docs/reference/src/api/msg/nng_msg_header_append.md deleted file mode 100644 index f87649a5..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_append.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_msg_header_append - -## NAME - -nng_msg_header_append --- append to message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_append(nng_msg *msg, const void *val, size_t size); -int nng_msg_header_append_u16(nng_msg *msg, uint16_t val16); -int nng_msg_header_append_u32(nng_msg *msg, uint32_t val32); -int nng_msg_header_append_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_header_append()` family of functions appends data to -the end of the headers of message _msg_, reallocating it if necessary. -The first function appends _size_ bytes, copying them from _val_. - -The remaining functions append the value (such as _val32_) in -network-byte order (big-endian). - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_chop.md b/docs/reference/src/api/msg/nng_msg_header_chop.md deleted file mode 100644 index 9419d88f..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_chop.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header_chop - -## NAME - -nng_msg_header_chop --- remove data from end of message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_chop(nng_msg *msg, size_t size); -int nng_msg_header_chop_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_header_chop_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_header_chop_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_header_chop()` family of functions removes -data from the end of the header of message _msg_. -The first function removes _size_ bytes. -The remaining functions remove 2, 4, or 8 bytes, and stores them in the value -(such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -## RETURN VALUES - -These function return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message header is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_clear.md b/docs/reference/src/api/msg/nng_msg_header_clear.md deleted file mode 100644 index 7f3b8387..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_clear.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_msg_header_clear - -## NAME - -nng_msg_header_clear --- clear message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_header_clear(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_clear()` function resets the header length of _msg_ to zero. - -## SEE ALSO - -[nng_msg_header](nng_msg_header.md), -[nng_msg_header_len](nng_msg_header_len.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_insert.md b/docs/reference/src/api/msg/nng_msg_header_insert.md deleted file mode 100644 index 07124fd9..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_insert.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_msg_header_insert - -## NAME - -nng_msg_header_insert --- prepend to message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_insert(nng_msg *msg, const void *val, size_t size); -int nng_msg_header_insert_u16(nng_msg *msg, uint16_t val16); -int nng_msg_header_insert_u32(nng_msg *msg, uint32_t val32); -int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_header_insert()` family of functions -prepends data to the front of the headers of message _msg_, reallocating -if necessary. -The first function prepends _size_ bytes, copying them from _val_. -The remaining functions prepend the specified value (such as _val32_) in -network-byte order (big-endian). - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md) -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_len.md b/docs/reference/src/api/msg/nng_msg_header_len.md deleted file mode 100644 index 51bbf537..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_len.md +++ /dev/null @@ -1,25 +0,0 @@ -# nng_msg_header_len - -## NAME - -nng_msg_header_len --- return message header length - -## SYNOPSIS - -```c -#include <nng/nng.h> - -size_t nng_msg_header_len(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_header_len()` returns the length of message header of _msg_. - -## RETURN VALUES - -Length of message header. - -## SEE ALSO - -[nng_msg_header](nng_msg_header) diff --git a/docs/reference/src/api/msg/nng_msg_header_trim.md b/docs/reference/src/api/msg/nng_msg_header_trim.md deleted file mode 100644 index ef596dbc..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_trim.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header_trim - -## NAME - -nng_msg_header_trim --- remove data from start of message header - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_header_trim(nng_msg *msg, size_t size); -int nng_msg_header_trim_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_header_trim_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_header_trim()` family of functions remove -data from the start of the header of message _msg_. -The first function removes _size_ bytes. -The remaining functions removes 2, 4, or 8 bytes, and stores them in the -value (such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message header is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.md) -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), diff --git a/docs/reference/src/api/msg/nng_msg_insert.md b/docs/reference/src/api/msg/nng_msg_insert.md deleted file mode 100644 index a369d3c4..00000000 --- a/docs/reference/src/api/msg/nng_msg_insert.md +++ /dev/null @@ -1,53 +0,0 @@ -# nng_msg_insert - -## NAME - -nng_msg_insert --- prepend to message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_insert(nng_msg *msg, const void *val, size_t size); -int nng_msg_insert_u16(nng_msg *msg, uint16_t val16); -int nng_msg_insert_u32(nng_msg *msg, uint32_t val32); -int nng_msg_insert_u64(nng_msg *msg, uint64_t val64); -``` - -## DESCRIPTION - -The `nng_msg_insert()` family of functions prepends data to -the front of the body of message _msg_, reallocating it if necessary. -The first function prepends _size_ bytes, copying them from _val_. -The remaining functions prepend the specified value (such as _val32_) -in network-byte order (big-endian). - -> [!TIP] -> These functions make use of space pre-allocated in front of the -> message body if available, so they can often avoid performing any reallocation. -> Applications should use these instead of reallocating and copying message -> content themselves, in order to benefit from this capability. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_len.md b/docs/reference/src/api/msg/nng_msg_len.md deleted file mode 100644 index c470955c..00000000 --- a/docs/reference/src/api/msg/nng_msg_len.md +++ /dev/null @@ -1,26 +0,0 @@ -# nng_msg_len - -## NAME - -nng_msg_len --- return message body length - -## SYNOPSIS - -```c -#include <nng/nng.h> - -size_t nng_msg_len(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_len()` returns the length of the body of message _msg_. - -## RETURN VALUES - -Length of message body. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc), -[nng_msg_body](nng_msg_body) diff --git a/docs/reference/src/api/msg/nng_msg_realloc.md b/docs/reference/src/api/msg/nng_msg_realloc.md deleted file mode 100644 index 66d113aa..00000000 --- a/docs/reference/src/api/msg/nng_msg_realloc.md +++ /dev/null @@ -1,53 +0,0 @@ -# nng_msg_realloc(3) - -## NAME - -nng_msg_realloc --- reallocate a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_realloc(nng_msg *msg, size_t size); -``` - -## DESCRIPTION - -The `nng_msg_realloc()` function re-allocates a message so that it has -a body of length _size_. -This message attempts to avoid extra allocations, -and will reuse the existing memory when possible. - -TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data. -When appending many small pieces of data to a message using [`nng_msg_append()`](nng_msg_append.md), -allocations may be reduced by first using -[`nng_msg_reserve()`](nng_msg_reserve.md) -to create sufficient space. -In any case, reallocating or appending to a message is guaranteed to succeed if the resulting -body length is less than [`nng_msg_capacity()`](nng_msg_capacity.md). - -> [!NOTE] -> Pointers to message body and header content obtained prior to this -> function must not be in use, as the underlying memory used for the message -> may have changed, particularly if the message size is increasing. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_chop](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_reserve.md b/docs/reference/src/api/msg/nng_msg_reserve.md deleted file mode 100644 index 2d96ac8b..00000000 --- a/docs/reference/src/api/msg/nng_msg_reserve.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_msg_reserve - -## NAME - -nng_msg_reserve --- reserve storage for a message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_reserve(nng_msg *msg, size_t capacity); -``` - -## DESCRIPTION - -The `nng_msg_reserve()` function ensures a message has allocated enough storage -to accommodate a body of the given length. -This message attempts to avoid extra allocations, -and will reuse the existing memory when possible. - -> [!TIP] -> Using this message before [`nng_msg_append()`](nng_msg_append.md) -> will prevent additional memory allocations until the message's length exceeds -> the alotted capacity. - -> [!IMPORTANT] -> Pointers to message body and header content obtained prior to this -> function must not be in use, as the underlying memory used for the message -> may have changed, particularly if the message capacity is increasing. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md) diff --git a/docs/reference/src/api/msg/nng_msg_set_pipe.md b/docs/reference/src/api/msg/nng_msg_set_pipe.md deleted file mode 100644 index 58f339ca..00000000 --- a/docs/reference/src/api/msg/nng_msg_set_pipe.md +++ /dev/null @@ -1,29 +0,0 @@ -# nng_msg_set_pipe - -## NAME - -nng_msg_set_pipe --- set pipe for message - -## SYNOPSIS - -```c -#include <nng/nng.h> - -void nng_msg_set_pipe(nng_msg *msg, nng_pipe p); -``` - -## DESCRIPTION - -The `nng_msg_set_pipe()` sets the pipe associated with message _m_ to _p_. -This is most often useful when used with protocols that support directing -a message to a specific peer. -For example the [_PAIR_](../protocols/pair.md) version 1 protocol can do -this when `NNG_OPT_PAIR1_POLY` mode is set. - -> [!NOTE] -> Not all protocols support overriding the destination pipe. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_get_pipe](nng_msg_get_pipe.md) diff --git a/docs/reference/src/api/msg/nng_msg_trim.md b/docs/reference/src/api/msg/nng_msg_trim.md deleted file mode 100644 index c0b8f694..00000000 --- a/docs/reference/src/api/msg/nng_msg_trim.md +++ /dev/null @@ -1,48 +0,0 @@ -# nng_msg_trim - -## NAME - -nng_msg_trim --- remove data from start of message body - -## SYNOPSIS - -```c -#include <nng/nng.h> - -int nng_msg_trim(nng_msg *msg, size_t size); -int nng_msg_trim_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_trim_u64(nng_msg *msg, uint64_t *val64); -``` - -## DESCRIPTION - -The `nng_msg_trim()` family of functions removes data from -the start of the body of message _msg_. -The first function removes _size_ bytes. -The remaining functions remove 2, 4, or 8 bytes, and stores them in the value -(such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_EINVAL`: The message body is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_append](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_capacity](nng_msg_capacity.md), -[nng_msg_chop](nng_msg_chop.md) -[nng_msg_clear](nng_msg_chop.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_alloc.md b/docs/reference/src/api/threads/nng_cv_alloc.md deleted file mode 100644 index faa18ba4..00000000 --- a/docs/reference/src/api/threads/nng_cv_alloc.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_cv_alloc - -## NAME - -nng_cv_alloc --- allocate condition variable - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -typedef struct nng_cv nng_cv; - -int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_cv_alloc()` function allocates a condition variable, using -the mutex _mtx_, and returns it in _cvp_. - -Every condition variable is associated with a mutex, which must be -owned when a thread waits for the condition using -[`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md). -The mutex must also be owned when signaling the condition using the -[`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md) functions. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_cv_free](nng_cv_free.md), -[nng_cv_until](nng_cv_until.md), -[nng_cv_wait](nng_cv_wait.md), -[nng_cv_wake](nng_cv_wake.md), -[nng_cv_wake1](nng_cv_wake1.md), -[nng_mtx_alloc](nng_mtx_alloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_free.md b/docs/reference/src/api/threads/nng_cv_free.md deleted file mode 100644 index f7103f66..00000000 --- a/docs/reference/src/api/threads/nng_cv_free.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_cv_free - -## NAME - -nng_cv_free --- free condition variable - -### SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_cv_free(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_free()` function frees the condition variable _cv_. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_until.md b/docs/reference/src/api/threads/nng_cv_until.md deleted file mode 100644 index 620b46b7..00000000 --- a/docs/reference/src/api/threads/nng_cv_until.md +++ /dev/null @@ -1,75 +0,0 @@ -# nng_cv_until() - -## NAME - -nng_cv_until --- wait for condition or timeout - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -int nng_cv_until(nng_cv *cv, nng_time when); -``` - -## DESCRIPTION - -The `nng_cv_until()` waits until either the condition variable _cv_ is signaled -by another thread calling either -[`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md), or the system clock (as tracked -by [`nng_clock()`](../util/nng_clock.md)) reaches _when_. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -Spurious wakeups can occur. - -> [!TIP] -> Any condition may be used or checked, but the condition must be -> checked, as it is possible for this function to wake up spuriously. -> The best way to do this is inside a loop that repeats until the condition -> tests for true. - -## EXAMPLE - -The following example demonstrates use of this function: - -### Example 1: Waiting for the condition - -```c - expire = nng_clock() + 1000; // 1 second in the future - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) { - printf("Time out reached!\n"); - break; - } - } - // condition_true is true - nng_mtx_unlock(m); -``` - -### Example 2: Signaling the condition - -```c - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); -``` - -## SEE ALSO - -[nng_clock()](../util/nng_clock.md), -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wait.md b/docs/reference/src/api/threads/nng_cv_wait.md deleted file mode 100644 index d384201c..00000000 --- a/docs/reference/src/api/threads/nng_cv_wait.md +++ /dev/null @@ -1,68 +0,0 @@ -# nng_cv_wait - -## NAME - -nng_cv_wait --- wait for condition - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_cv_wait(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled -by another thread calling either [`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md). - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -Spurious wakeups are possible. - -> [!TIP] -> Any condition may be used or checked, but the condition must be -> checked, as it is possible for this function to wake up spuriously. -> The best way to do this is inside a loop that repeats until the condition -> tests for true. - -## EXAMPLE - -The following example demonstrates use of this function: - -### Example 1: Waiting for the condition - -```c - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - nng_cv_wait(cv); - } - // condition_true is true - nng_mtx_unlock(m); -``` - -### Example 2: Signaling the condition - -```c - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); -``` - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_cv_until](nng_cv_until.md), -[nng_cv_wake](nng_cv_wake.md), -[nng_cv_wake1](nng_cv_wake1.md), -[nng_mtx_alloc](nng_mtx_alloc.md), -[nng_mtx_lock](nng_mtx_lock.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wake.md b/docs/reference/src/api/threads/nng_cv_wake.md deleted file mode 100644 index 8d0d2fbd..00000000 --- a/docs/reference/src/api/threads/nng_cv_wake.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_cv_wake - -## NAME - -nng_cv_wake --- wake all waiters - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_cv_wake(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ -to be signaled in the [`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md) functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -The caller should already have set the condition that the waiters -will check, while holding the mutex. - -> [!TIP] -> This function wakes all threads, which is generally safer but can -> lead to a performance problem when there are many waiters, as they are all -> woken simultaneously and may contend for resources. -> See [`nng_cv_wake1()`](nng_cv_wake1.md) for a solution to this problem. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_cv_until](nng_cv_until.md), -[nng_cv_wait](nng_cv_wait.md), -[nng_cv_wake1](nng_cv_wake1.md), -[nng_mtx_alloc](nng_mtx_alloc.md), -[nng_mtx_lock](nng_mtx_lock.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wake1.md b/docs/reference/src/api/threads/nng_cv_wake1.md deleted file mode 100644 index 09b31755..00000000 --- a/docs/reference/src/api/threads/nng_cv_wake1.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_cv_wake1 - -## NAME - -nng_cv_wake1 --- wake one waiter - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_cv_wake1(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_wake1()` wakes at most one thread waiting for the condition -variable _cv_ -to be signaled in the [`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md) functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -The caller should already have set the condition that the waiters -will check, while holding the mutex. - -> [!NOTE] -> The caller cannot predict which waiter will be woken, and so the design must -> ensure that it is sufficient that _any_ waiter be woken. -> When in doubt, it is safer to use [`nng_cv_wake()`](nng_cv_wake.md). - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_cv_until](nng_cv_until.md), -[nng_cv_wait](nng_cv_wait.md), -[nng_cv_wake](nng_cv_wake.md), -[nng_mtx_alloc](nng_mtx_alloc.md), -[nng_mtx_lock](nng_mtx_lock.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_alloc.md b/docs/reference/src/api/threads/nng_mtx_alloc.md deleted file mode 100644 index 64263d59..00000000 --- a/docs/reference/src/api/threads/nng_mtx_alloc.md +++ /dev/null @@ -1,44 +0,0 @@ -# nng_mtx_alloc - -## NAME - -nng_mtx_alloc - allocate mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -typedef struct nng_mtx nng_mtx; - -int nng_mtx_alloc(nng_mtx **mtxp); -``` - -## DESCRIPTION - -The `nng_mtx_alloc()` function allocates mutex and returns it in _mtxp_. - -The mutex objects created by this function are suitable only for -simple lock and unlock operations, and are not recursive. -Every effort has been made to use light-weight underlying primitives when available. - -Mutex (mutual exclusion) objects can be thought of as binary semaphores, -where only a single thread of execution is permitted to acquire the semaphore. - -Furthermore, a mutex can only be unlocked by the thread that locked it. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_mtx_free](nng_mtx_free.md), -[nng_mtx_lock](nng_mtx_lock.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_free.md b/docs/reference/src/api/threads/nng_mtx_free.md deleted file mode 100644 index a6fe7d7b..00000000 --- a/docs/reference/src/api/threads/nng_mtx_free.md +++ /dev/null @@ -1,23 +0,0 @@ -# nng_mtx_free - -## NAME - -nng_mtx_free --- free mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_mtx_free(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_free()` function frees the mutex _mtx_. -The mutex must not be locked when this function is called. - -## SEE ALSO - -[nng_mtx_alloc](nng_mtx_alloc) diff --git a/docs/reference/src/api/threads/nng_mtx_lock.md b/docs/reference/src/api/threads/nng_mtx_lock.md deleted file mode 100644 index 2e50f010..00000000 --- a/docs/reference/src/api/threads/nng_mtx_lock.md +++ /dev/null @@ -1,38 +0,0 @@ -# nng_mtx_lock - -## NAME - -nng_mtx_lock --- lock mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_mtx_lock(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. -If the lock is already owned, this function will wait until the current -owner releases it with [`nng_mtx_unlock()`](nng_mtx_unlock.md). - -If multiple threads are waiting for the lock, the order of acquisition -is not specified. - -> [!NOTE] -> A mutex can _only_ be unlocked by the thread that locked it. - -> [!NOTE] -> Mutex locks are _not_ recursive; attempts to reacquire the -> same mutex may result in deadlock or aborting the current program. -> It is a programming error for the owner of a mutex to attempt to -> reacquire it. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_mtx_alloc](nng_mtx_alloc.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_unlock.md b/docs/reference/src/api/threads/nng_mtx_unlock.md deleted file mode 100644 index d5815287..00000000 --- a/docs/reference/src/api/threads/nng_mtx_unlock.md +++ /dev/null @@ -1,29 +0,0 @@ -# nng_mtx_unlock(3supp) - -## NAME - -nng_mtx_unlock --- unlock mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_mtx_unlock(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_unlock()` relinquishes ownership of the mutex _mtx_ that -was previously acquired via [`nng_mtx_lock()`](nng_mtx_lock.md). - -> [!NOTE] -> A mutex can _only_ be unlocked by the thread that locked it. -> Attempting to unlock a mutex that is not owned by the caller will result -> in undefined behavior. - -## SEE ALSO - -[nng_mtx_alloc](nng_mtx_alloc), -[nng_mtx_lock](nng_mtx_lock) |