Libuv Thread Affinity, Priority, and Joining

49th chunk of `runtime/doc/luvref.txt`

c9bb51cce9d18d95d1aec1351ce317cdb75302e64eb9fb3a0000000100000fa0

 since
                `#affinity` will be used as the `cpumask_size` if it is
                greater than |uv.cpumask_size()|.

                If `get_old_affinity` is `true`, the previous affinity
                settings for the `thread` will be returned. Otherwise, `true`
                is returned after a successful call.

                Note: Thread affinity setting is not atomic on Windows.
                Unsupported on macOS.

                Returns: `table` or `boolean` or `fail`
                - `[1, 2, 3, ..., n]` : `boolean`


uv.thread_getaffinity({thread} [, {mask_size}])        *uv.thread_getaffinity()*

                > method form `thread:getaffinity([mask_size])`

                Parameters:
                - `thread`: `luv_thread_t userdata`
                - `mask_size`: `integer`

                Gets the specified thread's affinity setting.

                If `mask_size` is provided, it must be greater than or equal
                to `uv.cpumask_size()`. If the `mask_size` parameter is
                omitted, then the return of `uv.cpumask_size()` will be used.
                Returns an array-like table where each of the keys correspond
                to a CPU number and the values are booleans that represent
                whether the `thread` is eligible to run on that CPU.

                Note: Thread affinity getting is not atomic on Windows.
                Unsupported on macOS.

                Returns: `table` or `fail`
                - `[1, 2, 3, ..., n]` : `boolean`

uv.thread_getcpu()                                          *uv.thread_getcpu()*

                Gets the CPU number on which the calling thread is running.

                Note: The first CPU will be returned as the number 1, not 0.
                This allows for the number to correspond with the table keys
                used in `uv.thread_getaffinity` and `uv.thread_setaffinity`.

                Returns: `integer` or `fail`

uv.thread_setpriority({thread}, {priority})            *uv.thread.setpriority()*

                > method form `thread:setpriority(priority)`

                Parameters:
                - `thread`: `luv_thread_t userdata`
                - `priority`: `number`

                Sets the specified thread's scheduling priority setting. It
                requires elevated privilege to set specific priorities on some
                platforms. The priority can be set to the following constants:
                - `uv.constants.THREAD_PRIORITY_HIGHEST`
                - `uv.constants.THREAD_PRIORITY_ABOVE_NORMAL`
                - `uv.constants.THREAD_PRIORITY_NORMAL`
                - `uv.constants.THREAD_PRIORITY_BELOW_NORMAL`
                - `uv.constants.THREAD_PRIORITY_LOWEST`

                Returns: `boolean` or `fail`

uv.thread_getpriority({thread})                        *uv.thread.getpriority()*

                > method form `thread:getpriority()`

                Parameters:
                - `thread`: `luv_thread_t userdata`

                Gets the thread's priority setting.

                Retrieves the scheduling priority of the specified thread. The
                returned priority value is platform dependent.

                For Linux, when schedule policy is SCHED_OTHER (default),
                priority is 0.

                Returns: `number` or `fail`

uv.thread_self()                                              *uv.thread_self()*

                Returns the handle for the thread in which this is called.

                Returns: `luv_thread_t`

uv.thread_join({thread})                                      *uv.thread_join()*

                > method form `thread:join()`

                Parameters:
                - `thread`: `luv_thread_t userdata`

                Waits for the `thread` to finish executing its entry function.

                Returns: `boolean` or `fail`

uv.thread_detach({thread})                                  *uv.thread_detach()*

Title: Libuv Thread Affinity, Priority, and Joining

Summary

This section describes functions for managing threads in Libuv, including getting the CPU affinity (`uv.thread_getaffinity`), getting the CPU number for the current thread (`uv.thread_getcpu`), setting thread priority (`uv.thread_setpriority`), getting thread priority (`uv.thread_getpriority`), getting the handle for the current thread (`uv.thread_self`), waiting for a thread to finish (`uv.thread_join`). It also covers detaching a thread (`uv.thread_detach`). Each function's parameters, return values, and platform-specific notes (Windows and macOS) are detailed.