From b61ba4635d2fae0a03567feaf8a8e85d1a601d3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Thu, 30 May 2024 09:19:05 +0200 Subject: [PATCH 1/5] doc: clarify uv_fs_t.result --- docs/src/fs.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/src/fs.rst b/docs/src/fs.rst index 891ee74c..84b0a020 100644 --- a/docs/src/fs.rst +++ b/docs/src/fs.rst @@ -190,9 +190,13 @@ Public members .. c:member:: ssize_t uv_fs_t.result - Result of the request. < 0 means error, success otherwise. On requests such - as :c:func:`uv_fs_read` or :c:func:`uv_fs_write` it indicates the amount of - data that was read or written, respectively. + Result of the request. < 0 means error, success otherwise. This field is always set, regardless + of the request being sync or async. + + For synchronous calls, the result of each operation is this field. + + Check each function's documentation to check if the field has + an extended meaning. .. c:member:: uv_stat_t uv_fs_t.statbuf @@ -232,6 +236,8 @@ API Equivalent to :man:`preadv(2)`. If the `offset` argument is `-1`, then the current file offset is used and updated. + The result in `req->result` indicates the amount of bytes read, if > 0. + .. warning:: On Windows, under non-MSVC environments (e.g. when GCC or Clang is used to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal @@ -246,6 +252,8 @@ API Equivalent to :man:`pwritev(2)`. If the `offset` argument is `-1`, then the current file offset is used and updated. + The result in `req->result` indicates the amount of bytes written, if > 0. + .. warning:: On Windows, under non-MSVC environments (e.g. when GCC or Clang is used to build libuv), files opened using ``UV_FS_O_FILEMAP`` may cause a fatal From 319ff98203a227ee8713d97e9afb3bed617187fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Thu, 30 May 2024 09:28:34 +0200 Subject: [PATCH 2/5] doc: clarify uv_fs_req_cleanup --- docs/src/fs.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/src/fs.rst b/docs/src/fs.rst index 84b0a020..6d7e55b6 100644 --- a/docs/src/fs.rst +++ b/docs/src/fs.rst @@ -215,8 +215,10 @@ API .. c:function:: void uv_fs_req_cleanup(uv_fs_t* req) - Cleanup request. Must be called after a request is finished to deallocate - any memory libuv might have allocated. + Cleanup request. Must be called after a request is finished to cleanup + any resources libuv might have allocated. + + It must be called for all requests, regardless of success or failure. .. c:function:: int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb) From f933b309f95a89bbeecddab345c660a9773e421c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Thu, 30 May 2024 09:36:35 +0200 Subject: [PATCH 3/5] doc: clarify us_fs_open --- docs/src/fs.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/src/fs.rst b/docs/src/fs.rst index 6d7e55b6..fc877e3b 100644 --- a/docs/src/fs.rst +++ b/docs/src/fs.rst @@ -228,6 +228,17 @@ API Equivalent to :man:`open(2)`. + The `req->result` field contains the opened file descriptor, of < 0 for error. + + The `flags` argument has different semantics depending on the OS: + + - On Unix, they are directly passed to :man:`open(2)`. + - On Windows, the following flags are implemented, emulating Unix semantics: `UV_FS_O_APPEND`, + `UV_FS_O_CREAT`, `UV_FS_O_EXCL`, `UV_FS_O_FILEMAP`, `UV_FS_O_RANDOM`, `UV_FS_O_RDONLY`, + `UV_FS_O_RDWR`, `UV_FS_O_SEQUENTIAL`, `UV_FS_O_SHORT_LIVED`, `UV_FS_O_TEMPORARY`, + `UV_FS_O_TRUNC`, `UV_FS_O_WRONLY`, `UV_FS_O_DIRECT`, `UV_FS_O_DSYNC`, `UV_FS_O_EXLOCK`, + `UV_FS_O_SYNC`. + .. note:: On Windows libuv uses `CreateFileW` and thus the file is always opened in binary mode. Because of this the O_BINARY and O_TEXT flags are not From 511315db04ab0d13594f39505264e74296e61143 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Thu, 30 May 2024 09:38:28 +0200 Subject: [PATCH 4/5] doc: fix rst syntax in uv_thread_setpriority --- docs/src/threading.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/src/threading.rst b/docs/src/threading.rst index 883218fa..d215e9b9 100644 --- a/docs/src/threading.rst +++ b/docs/src/threading.rst @@ -133,19 +133,26 @@ Threads .. c:function:: int uv_thread_equal(const uv_thread_t* t1, const uv_thread_t* t2) .. c:function:: int uv_thread_setpriority(uv_thread_t tid, int priority) + If the function succeeds, the return value is 0. If the function fails, the return value is less than zero. + Sets the scheduling priority of the thread specified by tid. It requires elevated privilege to set specific priorities on some platforms. - The priority can be set to the following constants. UV_THREAD_PRIORITY_HIGHEST, - UV_THREAD_PRIORITY_ABOVE_NORMAL, UV_THREAD_PRIORITY_NORMAL, - UV_THREAD_PRIORITY_BELOW_NORMAL, UV_THREAD_PRIORITY_LOWEST. + + The priority can be set to the following constants: `UV_THREAD_PRIORITY_HIGHEST`, + `UV_THREAD_PRIORITY_ABOVE_NORMAL`, `UV_THREAD_PRIORITY_NORMAL`, + `UV_THREAD_PRIORITY_BELOW_NORMAL`, `UV_THREAD_PRIORITY_LOWEST`. + .. c:function:: int uv_thread_getpriority(uv_thread_t tid, int* priority) + If the function succeeds, the return value is 0. If the function fails, the return value is less than zero. + Retrieves the scheduling priority of the thread specified by tid. The value in the output parameter priority is platform dependent. - For Linux, when schedule policy is SCHED_OTHER (default), priority is 0. + + For Linux, when schedule policy is `SCHED_OTHER` (default), priority is 0. Thread-local storage ^^^^^^^^^^^^^^^^^^^^ From 9e3644f9f5454f737cc94e2d1ddc0e3199255959 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Tue, 2 Jul 2024 09:10:55 +0200 Subject: [PATCH 5/5] doc: add warning about uv_close --- docs/src/handle.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/src/handle.rst b/docs/src/handle.rst index e91d6e8f..ae0632f8 100644 --- a/docs/src/handle.rst +++ b/docs/src/handle.rst @@ -156,6 +156,10 @@ API `close_cb` can be `NULL` in cases where no cleanup or deallocation is necessary. + .. warning:: + Calling this function multiple times is not supported and will produce + a crash. + .. c:function:: void uv_ref(uv_handle_t* handle) Reference the given handle. References are idempotent, that is, if a handle