gre-ilya/libuv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: clarify uv_buf_t usage in uv_alloc_cb

Browse Source 
Clarify the uv_buf_t isn't reused and the user is responsible for
freeing it in the recv/read callback.

Previously, this wasn't clear when reading only the docs for
uv_udp_recv_cb and uv_alloc_cb.

PR-URL: https://github.com/libuv/libuv/pull/2438
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
This commit is contained in:
Tomas Krizek 2019-08-22 12:43:09 +02:00 committed by Santiago Gimeno
parent 1bd7cc5ce9
commit 641ec77265
No known key found for this signature in database
GPG Key ID: F28C3C8DA33C03BE
3 changed files with 12 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/src/handle.rst
View File

@ -60,6 +60,9 @@ Data types
a ``UV_ENOBUFS`` error will be triggered in the :c:type:`uv_udp_recv_cb` or the a ``UV_ENOBUFS`` error will be triggered in the :c:type:`uv_udp_recv_cb` or the
:c:type:`uv_read_cb` callback. :c:type:`uv_read_cb` callback.
Each buffer is used only once and the user is responsible for freeing it in the
:c:type:`uv_udp_recv_cb` or the :c:type:`uv_read_cb` callback.
A suggested size (65536 at the moment in most cases) is provided, but it's just an indication, A suggested size (65536 at the moment in most cases) is provided, but it's just an indication,
not related in any way to the pending data to be read. The user is free to allocate the amount not related in any way to the pending data to be read. The user is free to allocate the amount
of memory they decide. of memory they decide.

4
docs/src/stream.rst
View File

@ -50,8 +50,8 @@ Data types
from the stream again is undefined. from the stream again is undefined.
The callee is responsible for freeing the buffer, libuv does not reuse it. The callee is responsible for freeing the buffer, libuv does not reuse it.
The buffer may be a null buffer (where buf->base=NULL and buf->len=0) on The buffer may be a null buffer (where `buf->base` == NULL and `buf->len` == 0)
error. on error.
.. c:type:: void (*uv_write_cb)(uv_write_t* req, int status) .. c:type:: void (*uv_write_cb)(uv_write_t* req, int status)

11
docs/src/udp.rst
View File

@ -56,16 +56,19 @@ Data types
* `handle`: UDP handle * `handle`: UDP handle
* `nread`: Number of bytes that have been received. * `nread`: Number of bytes that have been received.
0 if there is no more data to read. You may discard or repurpose 0 if there is no more data to read. Note that 0 may also mean that an
the read buffer. Note that 0 may also mean that an empty datagram empty datagram was received (in this case `addr` is not NULL). < 0 if
was received (in this case `addr` is not NULL). < 0 if a transmission a transmission error was detected.
error was detected.
* `buf`: :c:type:`uv_buf_t` with the received data. * `buf`: :c:type:`uv_buf_t` with the received data.
* `addr`: ``struct sockaddr*`` containing the address of the sender. * `addr`: ``struct sockaddr*`` containing the address of the sender.
Can be NULL. Valid for the duration of the callback only. Can be NULL. Valid for the duration of the callback only.
* `flags`: One or more or'ed UV_UDP_* constants. Right now only * `flags`: One or more or'ed UV_UDP_* constants. Right now only
``UV_UDP_PARTIAL`` is used. ``UV_UDP_PARTIAL`` is used.
The callee is responsible for freeing the buffer, libuv does not reuse it.
The buffer may be a null buffer (where `buf->base` == NULL and `buf->len` == 0)
on error.
.. note:: .. note::
The receive callback will be called with `nread` == 0 and `addr` == NULL when there is The receive callback will be called with `nread` == 0 and `addr` == NULL when there is
nothing to read, and with `nread` == 0 and `addr` != NULL when an empty UDP packet is nothing to read, and with `nread` == 0 and `addr` != NULL when an empty UDP packet is