diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/man/libnng.3.adoc | 12 | ||||
| -rw-r--r-- | docs/man/nng_msg.5.adoc | 64 | ||||
| -rw-r--r-- | docs/man/nng_msg_alloc.3.adoc | 55 | ||||
| -rw-r--r-- | docs/man/nng_msg_capacity.3.adoc | 46 | ||||
| -rw-r--r-- | docs/man/nng_msg_dup.3.adoc | 49 | ||||
| -rw-r--r-- | docs/man/nng_msg_free.3.adoc | 43 | ||||
| -rw-r--r-- | docs/man/nng_msg_realloc.3.adoc | 66 | ||||
| -rw-r--r-- | docs/man/nng_msg_reserve.3.adoc | 63 | ||||
| -rw-r--r-- | docs/ref/SUMMARY.md | 4 | ||||
| -rw-r--r-- | docs/ref/api/msg/index.md | 5 | ||||
| -rw-r--r-- | docs/ref/api/msg/nng_msg.md | 147 |
11 files changed, 162 insertions, 392 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index e6a0da4b..e13ddf0b 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -98,19 +98,19 @@ user-payload and the header carries protocol specific header information. Most applications will only interact with the body. |=== -|xref:nng_msg_alloc.3.adoc[nng_msg_alloc()]|allocate a message +// |xref:nng_msg_alloc.3.adoc[nng_msg_alloc()]|allocate a message |xref:nng_msg_append.3.adoc[nng_msg_append()]|append to message body |xref:nng_msg_body.3.adoc[nng_msg_body()]|return message body -|xref:nng_msg_capacity.3.adoc[nng_msg_capacity()]|return capacity allocated for message body +// |xref:nng_msg_capacity.3.adoc[nng_msg_capacity()]|return capacity allocated for message body |xref:nng_msg_chop.3.adoc[nng_msg_chop()]|remove data from end of message body |xref:nng_msg_clear.3.adoc[nng_msg_clear()]|clear message body -|xref:nng_msg_dup.3.adoc[nng_msg_dup()]|duplicate a message -|xref:nng_msg_free.3.adoc[nng_msg_free()]|free a message +// |xref:nng_msg_dup.3.adoc[nng_msg_dup()]|duplicate a message +// |xref:nng_msg_free.3.adoc[nng_msg_free()]|free a message |xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe()]|get pipe for message |xref:nng_msg_insert.3.adoc[nng_msg_insert()]|prepend to message body |xref:nng_msg_len.3.adoc[nng_msg_len()]|return the message body length -|xref:nng_msg_realloc.3.adoc[nng_msg_realloc()]|reallocate a message -|xref:nng_msg_reserve.3.adoc[nng_msg_reserve()]|reserve storage for message body +// |xref:nng_msg_realloc.3.adoc[nng_msg_realloc()]|reallocate a message +// |xref:nng_msg_reserve.3.adoc[nng_msg_reserve()]|reserve storage for message body |xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe()]|set pipe for message |xref:nng_msg_trim.3.adoc[nng_msg_trim()]|remove data from start of message body |xref:nng_recvmsg.3.adoc[nng_recvmsg()]|receive a message diff --git a/docs/man/nng_msg.5.adoc b/docs/man/nng_msg.5.adoc deleted file mode 100644 index 5044cf18..00000000 --- a/docs/man/nng_msg.5.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_msg(5) -// -// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg - message - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -typedef struct nng_msg nng_msg; ----- - -== DESCRIPTION - -An `nng_msg` represents a single ((message)) sent between Scalability Protocols -peers. -Messages internally have a ((body)), containing the application supplied -payload, and a ((header)), containing protocol specific routing and similar -related information. - -TIP: Using message-oriented functions is a good way to reduce the likelihood -of data copies and improve application performance. - -Messages are allocated using the xref:nng_msg_alloc.3.adoc[`nng_msg_alloc()`] -function, and are deallocated using the xref:nng_msg_free.3.adoc[`nng_msg_free()`] -function. - -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. -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. - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_dup.3.adoc[nng_msg_dup(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_recvmsg.3.adoc[nng_recvmsg(3)], -xref:nng_sendmsg.3.adoc[nng_sendmsg(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_alloc.3.adoc b/docs/man/nng_msg_alloc.3.adoc deleted file mode 100644 index 2754b67e..00000000 --- a/docs/man/nng_msg_alloc.3.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_msg_alloc(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_alloc - allocate a message - -== SYNOPSIS - -[source, 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 - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_dup.3.adoc[nng_msg_dup(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_capacity.3.adoc b/docs/man/nng_msg_capacity.3.adoc deleted file mode 100644 index ffc7f5d3..00000000 --- a/docs/man/nng_msg_capacity.3.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nng_msg_capacity(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_capacity - return message body length - -== SYNOPSIS - -[source, 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. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_dup.3.adoc b/docs/man/nng_msg_dup.3.adoc deleted file mode 100644 index b985d5bb..00000000 --- a/docs/man/nng_msg_dup.3.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nng_msg_dup(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_dup - duplicate a message - -== SYNOPSIS - -[source, 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 - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_free.3.adoc b/docs/man/nng_msg_free.3.adoc deleted file mode 100644 index 1ee045c0..00000000 --- a/docs/man/nng_msg_free.3.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= nng_msg_free(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_free - free a message - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -void nng_msg_free(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_free()` function deallocates the message _msg_ entirely. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_realloc.3.adoc b/docs/man/nng_msg_realloc.3.adoc deleted file mode 100644 index bf407289..00000000 --- a/docs/man/nng_msg_realloc.3.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= nng_msg_realloc(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_realloc - reallocate a message - -== SYNOPSIS - -[source, 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 xref:nng_msg_append.3.adoc[`nng_msg_append()`], -allocations may be reduced by first using xref:nng_msg_reserve.3.adoc[`nng_msg_reserve()`] -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 xref:nng_msg_capacity.3.adoc[`nng_msg_capacity()`]. - -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 - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_reserve.3.adoc b/docs/man/nng_msg_reserve.3.adoc deleted file mode 100644 index 254c1e94..00000000 --- a/docs/man/nng_msg_reserve.3.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_msg_reserve(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_reserve - reserve storage for a message - -== SYNOPSIS - -[source, 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 xref:nng_msg_append.3.adoc[`nng_msg_append()`] -will prevent additional memory allocations until the message's length exceeds -the alotted capacity. - -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 capacity is increasing. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index eb20a8c8..7e9bcc2d 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -2,6 +2,10 @@ - [API Reference](./api/index.md) + - [Messages](./api/msg/index.md) + + - [nng_msg](./api/msg/nng_msg.md) + - [Threading and Synchronization](./api/thr/index.md) - [nng_cv](./api/thr/nng_cv.md) diff --git a/docs/ref/api/msg/index.md b/docs/ref/api/msg/index.md new file mode 100644 index 00000000..18a3f620 --- /dev/null +++ b/docs/ref/api/msg/index.md @@ -0,0 +1,5 @@ +# Messages + +These interfaces deal with messages, used in the Scalability Protocols. + +- [nng_msg](./nng_msg.md) --- message diff --git a/docs/ref/api/msg/nng_msg.md b/docs/ref/api/msg/nng_msg.md new file mode 100644 index 00000000..84d6c273 --- /dev/null +++ b/docs/ref/api/msg/nng_msg.md @@ -0,0 +1,147 @@ +# nng_msg + +## NAME + +nng_msg --- message + +## SYNOPSIS + +```c +#include <nng/nng.h> + +typedef struct nng_msg nng_msg; + +int nng_msg_alloc(nng_msg **msgp, size_t size); +void nng_msg_free(nng_msg *msg); +int nng_msg_dup(nng_msg **dup, nng_msg *msg); +int nng_msg_realloc(nng_msg **msgp, size_t size); +int nng_msg_reserve(nng_msg *msg, size_t capacity); +size_t nng_msg_capacity(nng_msg *msg); +``` + +## DESCRIPTION + +An {{i:`nng_msg`}} represents a single {{i:message}} sent between Scalability Protocols peers. + +Messages in Scalability Protocols are the fundamental unit of transmission and reception, +as these protocols are fundamentally message-oriented. + +> [!NOTE] +> 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. + +Messages have a [body][nng_msg_body]{{hi:body}}, containing the application-supplied +payload, and a [header][nng_msg_header]{{hi:header}}, containing protocol specific routing and similar +related information. + +> [!TIP] +> Only applications using [raw mode][raw] need to access the message header. + +### Creating and Destroying Messages + +Messages are allocated using {{i:`nng_msg_alloc`}}, +and are deallocated using {{i:`nng_msg_free`}}. + +The `nng_msg_alloc` function takes a _size_ argument, and returns a message +with a preallocated body of that size in the _msgp_ parameter. + +Messages can be deallocated when no longer needed using `nng_msg_free`. + +A message may be duplicated using the {{i:`nng_msg_dup`}} function, which can be useful +when a copy must be saved or modified. The contents of the duplicate message will +be the same, but the actual pointers may be different, and the amount of reserved +space may be different as well. + +### Message Size and Capacity + +The message size may be changed by use of the {{i:`nng_msg_realloc`}} function. This +function will reallocate the underlying memory for the message referenced by _msgp_, +preserving contents, to provide the new buffer, and return the new message in _msgp_. +If the new size is smaller than the original message, it will +truncate the message, but not perform any allocations. +If the new message is different, then the original is freed. +If reallocation fails due to insufficient memory, then the original is left intact. + +If message growth is anticipated, the {{i:`nng_msg_reserve`}} function can be used +to ensure that the buffers underlying the message will be sufficient to hold a message +of at least _capacity_ bytes. The actual message {{i:capacity}} can be obtained using the +{{i:`nng_msg_capacity`}}. As long as the new size will not exceeed that capacity, +any functions that change the message will do so without an allocation, and are guaranteed +to succeed. + +> [!IMPORTANT] +> Any pointers to message content obtained before a call to `nng_msg_realloc` or +> `nng_msg_reserve` (or any other function that changes the message size) should be +> treated as invalid, as the locations pointed to may be deallocated by these functions. + +### 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 "{{i:headroom}}" and "{{i:tailroom}}", are automatically +included when allocating a message. + +Using `nng_msg_reserve` to ensure that adequate buffer space is availabe +in advance can reduce repeated allocations and data copies when modifying messages. + +## RETURN VALUES + +The `nng_msg_alloc`, `nng_msg_dup`, `nng_msg_realloc`, and `nng_msg_reserve` +functions return zero on success, or an error value on failure, typically `NNG_ENOMEM`. + +The `nng_msg_capacity` function returns the total body capacity of the message _msg_. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists to perform the operation. + +## 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][nng_aio_get_msg], +[nng_msg_body][nng_msg_body], +[nng_msg_header][nng_msg_header], +[nng_msg_set_pipe][nng_msg_set_pipe], +[nng_recvmsg][nng_recvmsg], +[nng_sendmsg][nng_sendmsg] + +[nng_msg_body]: ./nng_msg_body.md +[nng_msg_header]: ./nng_msg_header.md +[nng_msg_set_pipe]: ./nng_msg_set_pipe.md +[nng_aio_get_msg]: TODO.md +[nng_aio_set_msg]: TODO.md +[nng_recvmsg]: TODO.md +[nng_sendmsg]: TODO.md +[raw]: TODO.md |