unix,win: add uv_library_shutdown()

Make it possible to explicitly tell libuv to release any resources
it's still holding onto (memory, threads, file descriptors, etc.)

Before this commit, cleanup was performed in various destructors.
This commit centralizes the cleanup logic, enabling the addition of
`uv_library_shutdown()`, but maintains the current observable behavior
of cleaning up when libuv is unloaded by means of `dlclose(3)`.

Fixes: https://github.com/libuv/libuv/issues/2763
PR-URL: https://github.com/libuv/libuv/pull/2764
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/src/misc.rst b/docs/src/misc.rst
index 7640b8b0..7bf71b12 100644
--- a/docs/src/misc.rst
+++ b/docs/src/misc.rst
@@ -233,6 +233,22 @@ API
                  sure the allocator is changed while no memory was allocated with
                  the previous allocator, or that they are compatible.
 
+.. c:function:: void uv_library_shutdown(void);
+
+    .. versionadded:: 1.38.0
+
+    Release any global state that libuv is holding onto. Libuv will normally
+    do so automatically when it is unloaded but it can be instructed to perform
+    cleanup manually.
+
+    .. warning:: Only call :c:func:`uv_library_shutdown()` once.
+
+    .. warning:: Don't call :c:func:`uv_library_shutdown()` when there are
+    still event loops or I/O requests active.
+
+    .. warning:: Don't call libuv functions after calling
+    :c:func:`uv_library_shutdown()`.
+
 .. c:function:: uv_buf_t uv_buf_init(char* base, unsigned int len)
 
     Constructor for :c:type:`uv_buf_t`.