diff options
Diffstat (limited to 'docs/ref/api')
| -rw-r--r-- | docs/ref/api/memory.md | 4 | ||||
| -rw-r--r-- | docs/ref/api/sock.md | 28 |
2 files changed, 3 insertions, 29 deletions
diff --git a/docs/ref/api/memory.md b/docs/ref/api/memory.md index c5ecb23a..d8c5ecf9 100644 --- a/docs/ref/api/memory.md +++ b/docs/ref/api/memory.md @@ -19,9 +19,7 @@ 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`]. +Memory returned by `nng_alloc` should 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. diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md index 3ea056fb..ec6b20e1 100644 --- a/docs/ref/api/sock.md +++ b/docs/ref/api/sock.md @@ -177,13 +177,6 @@ made up of zero or more of the following values: If the socket cannot accept more data at this time, it does not block, but returns immediately with a status of [`NNG_EAGAIN`]. If this flag is absent, the function will wait until data can be sent. -- {{i:`NNG_FLAG_ALLOC`}}: <a name="NNG_FLAG_ALLOC"></a> - The _data_ was allocated using [`nng_alloc`] or was obtained from a call to [`nng_recv`] also with - the `NNG_FLAG_ALLOC` flag. If this function succeeds, then it will dispose of the _data_, deallocating it - once the transmission is complete. If this function returns a non-zero status, the caller retains the responsibility - of disposing the data. The benefit of this flag is that it can eliminate a data copy and allocation. Without the flag - the socket will make a duplicate copy of _data_ for use by the operation, before returning to the caller. - > [!NOTE] > Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may > be queues between the sender and the receiver. @@ -191,11 +184,6 @@ made up of zero or more of the following values: > Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`, > such as with [PUB][pub] sockets, which are best-effort delivery only. -> [!IMPORTANT] -> When using `NNG_FLAG_ALLOC`, it is important that the value of _size_ match the actual allocated size of the data. -> Using an incorrect size results in unspecified behavior, which may include heap corruption, program crashes, -> or other undesirable effects. - ### nng_sendmsg The `nng_sendmsg` function sends the _msg_ over the socket _s_. @@ -248,8 +236,7 @@ messages over the socket _s_. The differences in their behaviors are as follows. ### nng_recv The `nng_recv` function is the simplest to use, but is the least efficient. -It receives the content in _data_, as a message size (in bytes) of up to the value stored in _sizep_, -unless the `NNG_FLAG_ALLOC` flag is set in _flags_ (see below.) +It receives the content in _data_, as a message size (in bytes) of up to the value stored in _sizep_. Upon success, the size of the message received will be stored in _sizep_. @@ -259,17 +246,6 @@ The _flags_ is a bit mask made up of zero or more of the following values: If the socket has no messages pending for reception at this time, it does not block, but returns immediately with a status of [`NNG_EAGAIN`]. If this flag is absent, the function will wait until data can be received. -- {{i:`NNG_FLAG_ALLOC`}}: - Instead of receiving the message into _data_, a new buffer will be allocated exactly large enough to hold - the message. A pointer to that buffer will be stored at the location specified by _data_. This provides a form - of zero-copy operation. The caller should dispose of the buffer using [`nng_free`] or by sending using - [`nng_send`] with the [`NNG_FLAG_ALLOC`] flag. - -> [!IMPORTANT] -> When using `NNG_FLAG_ALLOC`, it is important that the value of _size_ match the actual allocated size of the data. -> Using an incorrect size results in unspecified behavior, which may include heap corruption, program crashes, -> or other undesirable effects. - ### nng_recvmsg The `nng_recvmsg` function receives a message and stores a pointer to the [`nng_msg`] for that message in _msgp_. @@ -279,7 +255,7 @@ has no messages available to receive. In such a case, it will return [`NNG_EAGAI > [!TIP] > This function is preferred over [`nng_recv`], as it gives access to the message structure and eliminates both -> a data copy and allocation, even when `nng_recv` is using `NNG_FLAG_ALLOC`. +> a data copy and allocation. ### nng_recv_aio |