Add & document msg_capacity, msg_reserve (#1458)

* Add & document msg_capacity, msg_reserve

* reserve/capacity code style

* Documentation references to reserve/capacity

13 files changed, 156 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)]
diff --git a/include/nng/nng.h b/include/nng/nng.h
index 65031d32..9c38febd 100644
--- a/include/nng/nng.h
+++ b/include/nng/nng.h
@@ -594,6 +594,8 @@ NNG_DECL void nng_sleep_aio(nng_duration, nng_aio *);
 NNG_DECL int      nng_msg_alloc(nng_msg **, size_t);
 NNG_DECL void     nng_msg_free(nng_msg *);
 NNG_DECL int      nng_msg_realloc(nng_msg *, size_t);
+NNG_DECL int      nng_msg_reserve(nng_msg *, size_t);
+NNG_DECL size_t   nng_msg_capacity(nng_msg *);
 NNG_DECL void *   nng_msg_header(nng_msg *);
 NNG_DECL size_t   nng_msg_header_len(const nng_msg *);
 NNG_DECL void *   nng_msg_body(nng_msg *);
diff --git a/src/core/message.c b/src/core/message.c
index 824fc079..52065bdd 100644
--- a/src/core/message.c
+++ b/src/core/message.c
@@ -456,6 +456,18 @@ nni_msg_realloc(nni_msg *m, size_t sz)
 	return (0);
 }
 
+int
+nni_msg_reserve(nni_msg *m, size_t capacity)
+{
+	return (nni_chunk_grow(&m->m_body, capacity, 0));
+}
+
+size_t
+nni_msg_capacity(nni_msg *m)
+{
+	return ((size_t) ((m->m_body.ch_buf + m->m_body.ch_cap) - m->m_body.ch_ptr));
+}
+
 void *
 nni_msg_header(nni_msg *m)
 {
diff --git a/src/core/message.h b/src/core/message.h
index 6400fd55..7e35ba75 100644
--- a/src/core/message.h
+++ b/src/core/message.h
@@ -17,6 +17,8 @@
 extern int      nni_msg_alloc(nni_msg **, size_t);
 extern void     nni_msg_free(nni_msg *);
 extern int      nni_msg_realloc(nni_msg *, size_t);
+extern int      nni_msg_reserve(nni_msg *, size_t);
+extern size_t   nni_msg_capacity(nni_msg *);
 extern int      nni_msg_dup(nni_msg **, const nni_msg *);
 extern void *   nni_msg_header(nni_msg *);
 extern size_t   nni_msg_header_len(const nni_msg *);
diff --git a/src/nng.c b/src/nng.c
index 3a3c3c5c..1ccc1386 100644
--- a/src/nng.c
+++ b/src/nng.c
@@ -1325,6 +1325,18 @@ nng_msg_free(nng_msg *msg)
 	nni_msg_free(msg);
 }
 
+int
+nng_msg_reserve(nng_msg *msg, size_t capacity)
+{
+	return (nni_msg_reserve(msg, capacity));
+}
+
+size_t
+nng_msg_capacity(nng_msg *msg)
+{
+	return (nni_msg_capacity(msg));
+}
+
 void *
 nng_msg_body(nng_msg *msg)
 {