From 8837141d860f7458bc3e615b68a11ce1ef541ceb Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Sun, 21 Dec 2025 13:08:45 +0100 Subject: [PATCH] doc: add handle and request usage guidelines Refs: https://github.com/libuv/libuv/discussions/4977 --- docs/src/design.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/src/design.rst b/docs/src/design.rst index 5a20595c3..7ad62076f 100644 --- a/docs/src/design.rst +++ b/docs/src/design.rst @@ -36,6 +36,31 @@ Requests represent (typically) short-lived operations. These operations can be p handle: write requests are used to write data on a handle; or standalone: getaddrinfo requests don't need a handle they run directly on the loop. +Guidelines for dealing with handles and requests: + +1. If `uv_foo_init()` succeeds in initializing the handle, you must call + :c:func:`uv_close()`. If the handle's init function errors, you don't + need to do anything. + +2. Only handles are closed, not requests. For example, :c:type:`uv_tcp_t` + is a handle, :c:type:`uv_write_t` is a request. + +3. The handle's memory can only be reclaimed or reused from inside the + :c:type:`uv_close_cb` or afterwards, not before. + +4. Most handles have init + start/stop functions; some handles don't. + Example: :c:type:`uv_tcp_t` vs. :c:type:`uv_process_t`; :c:func:`uv_spawn()` + combines handle initialization and process start into one. + +5. Requests are closed automatically when they complete, or when they are + cancelled with :c:func:`uv_cancel()`. + +6. No additional cleanup is needed except for :c:type:`uv_fs_t` and + :c:type:`uv_getaddrinfo_t` requests. For :c:type:`uv_fs_t`, call + :c:func:`uv_fs_req_cleanup()` once you are done with it; for + :c:type:`uv_getaddrinfo_t`, that's :c:func:`uv_freeaddrinfo()`. + +7. The request's memory can only be reclaimed or reused from that point onward. The I/O loop ^^^^^^^^^^^^