doc: clarify expected memory management strategy

Right now, docs don't make it clear when exactly does it become okay to free memory belonging to `uv_handle_t`. It's only stated that `uv_close` must be called before freeing the memory, which is a source of confusion for new users: they call `uv_close(handle, NULL)`, then free the memory (see e.g. libuv#2078, https://stackoverflow.com/q/25615340). PR-URL: libuv#2087 Reviewed-By: Ben Noordhuis <[email protected]>
tidemmo · Dec 2, 2018 · 5b64cc6 · 5b64cc6
1 parent c5593b5
commit 5b64cc6
Showing 1 changed file with 2 additions and 0 deletions.
diff --git a/docs/src/handle.rst b/docs/src/handle.rst
@@ -140,6 +140,8 @@ API
 
     Request handle to be closed. `close_cb` will be called asynchronously after
     this call. This MUST be called on each handle before memory is released.
+    Moreover, the memory can only be released in `close_cb` or after it has
+    returned.
 
     Handles that wrap file descriptors are closed immediately but
     `close_cb` will still be deferred to the next iteration of the event loop.