aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/man/libnng.3.adoc2
-rw-r--r--docs/man/nng_msg.5.adoc2
-rw-r--r--docs/man/nng_msg_alloc.3.adoc2
-rw-r--r--docs/man/nng_msg_body.3.adoc2
-rw-r--r--docs/man/nng_msg_capacity.3.adoc46
-rw-r--r--docs/man/nng_msg_chop.3.adoc2
-rw-r--r--docs/man/nng_msg_header_insert.3.adoc2
-rw-r--r--docs/man/nng_msg_realloc.3.adoc15
-rw-r--r--docs/man/nng_msg_reserve.3.adoc63
9 files changed, 128 insertions, 8 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index a09b1db1..712bf0fb 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -104,6 +104,7 @@ Most applications will only interact with the body.
|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_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
@@ -112,6 +113,7 @@ Most applications will only interact with the body.
|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_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
index 6244116d..5044cf18 100644
--- a/docs/man/nng_msg.5.adoc
+++ b/docs/man/nng_msg.5.adoc
@@ -55,6 +55,8 @@ 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)],
diff --git a/docs/man/nng_msg_alloc.3.adoc b/docs/man/nng_msg_alloc.3.adoc
index a1dc1c2e..2754b67e 100644
--- a/docs/man/nng_msg_alloc.3.adoc
+++ b/docs/man/nng_msg_alloc.3.adoc
@@ -47,6 +47,8 @@ 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)],
diff --git a/docs/man/nng_msg_body.3.adoc b/docs/man/nng_msg_body.3.adoc
index e36e4bfd..ad0fa7b3 100644
--- a/docs/man/nng_msg_body.3.adoc
+++ b/docs/man/nng_msg_body.3.adoc
@@ -54,6 +54,8 @@ 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_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_msg_trim.3.adoc[nng_msg_trim(3)],
xref:nng_msg.5.adoc[nng_msg(5)],
diff --git a/docs/man/nng_msg_capacity.3.adoc b/docs/man/nng_msg_capacity.3.adoc
new file mode 100644
index 00000000..ffc7f5d3
--- /dev/null
+++ b/docs/man/nng_msg_capacity.3.adoc
@@ -0,0 +1,46 @@
+= 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_chop.3.adoc b/docs/man/nng_msg_chop.3.adoc
index 435d9776..b945f0bb 100644
--- a/docs/man/nng_msg_chop.3.adoc
+++ b/docs/man/nng_msg_chop.3.adoc
@@ -52,6 +52,8 @@ xref:nng_msg_body.3.adoc[nng_msg_body(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_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_msg_trim.3.adoc[nng_msg_trim(3)],
xref:nng_strerror.3.adoc[nng_strerror(3)],
diff --git a/docs/man/nng_msg_header_insert.3.adoc b/docs/man/nng_msg_header_insert.3.adoc
index 1f3f6c2e..a2bf0d63 100644
--- a/docs/man/nng_msg_header_insert.3.adoc
+++ b/docs/man/nng_msg_header_insert.3.adoc
@@ -53,6 +53,8 @@ xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)],
xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)],
xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)],
xref:nng_msg_free.3.adoc[nng_msg_free(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.7.adoc[nng(7)]
diff --git a/docs/man/nng_msg_realloc.3.adoc b/docs/man/nng_msg_realloc.3.adoc
index 4d57921b..bf407289 100644
--- a/docs/man/nng_msg_realloc.3.adoc
+++ b/docs/man/nng_msg_realloc.3.adoc
@@ -29,14 +29,12 @@ a body of length _size_.
This message attempts to avoid extra allocations,
and will reuse the existing memory when possible.
-TIP: One way to further reduce message allocations is to allocate a message
-larger than needed, then use this function or
-xref:nng_msg_chop.3.adoc[`nng_msg_chop()`] to reduce the message size
-to that actually needed.
-The extra space left
-over will still be present in the message, so that when the message size
-needs to grow due to this function or xref:nng_msg_append.3.adoc[`nng_msg_append()`]
-no actual memory allocations need to take place.
+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
@@ -54,6 +52,7 @@ This function returns 0 on success, and non-zero otherwise.
== 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)],
diff --git a/docs/man/nng_msg_reserve.3.adoc b/docs/man/nng_msg_reserve.3.adoc
new file mode 100644
index 00000000..254c1e94
--- /dev/null
+++ b/docs/man/nng_msg_reserve.3.adoc
@@ -0,0 +1,63 @@
+= 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)]
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2026-01-18 11:32:21 +0000