1 2.. _loop: 3 4:c:type:`uv_loop_t` --- Event loop 5================================== 6 7The event loop is the central part of libuv's functionality. It takes care 8of polling for i/o and scheduling callbacks to be run based on different sources 9of events. 10 11 12Data types 13---------- 14 15.. c:type:: uv_loop_t 16 17 Loop data type. 18 19.. c:enum:: uv_loop_option 20 21 Additional loop options. 22 See :c:func:`uv_loop_configure`. 23 24 :: 25 26 typedef enum { 27 UV_LOOP_BLOCK_SIGNAL = 0, 28 UV_METRICS_IDLE_TIME, 29 UV_LOOP_USE_IO_URING_SQPOLL 30 } uv_loop_option; 31 32.. c:enum:: uv_run_mode 33 34 Mode used to run the loop with :c:func:`uv_run`. 35 36 :: 37 38 typedef enum { 39 UV_RUN_DEFAULT = 0, 40 UV_RUN_ONCE, 41 UV_RUN_NOWAIT 42 } uv_run_mode; 43 44.. c:type:: void (*uv_walk_cb)(uv_handle_t* handle, void* arg) 45 46 Type definition for callback passed to :c:func:`uv_walk`. 47 48 49Public members 50^^^^^^^^^^^^^^ 51 52.. c:member:: void* uv_loop_t.data 53 54 Space for user-defined arbitrary data. libuv does not use and does not 55 touch this field. 56 57 58API 59--- 60 61.. c:function:: int uv_loop_init(uv_loop_t* loop) 62 63 Initializes the given `uv_loop_t` structure. 64 65.. c:function:: int uv_loop_configure(uv_loop_t* loop, uv_loop_option option, ...) 66 67 .. versionadded:: 1.0.2 68 69 Set additional loop options. You should normally call this before the 70 first call to :c:func:`uv_run` unless mentioned otherwise. 71 72 Returns 0 on success or a UV_E* error code on failure. Be prepared to 73 handle UV_ENOSYS; it means the loop option is not supported by the platform. 74 75 Supported options: 76 77 - UV_LOOP_BLOCK_SIGNAL: Block a signal when polling for new events. The 78 second argument to :c:func:`uv_loop_configure` is the signal number. 79 80 This operation is currently only implemented for SIGPROF signals, 81 to suppress unnecessary wakeups when using a sampling profiler. 82 Requesting other signals will fail with UV_EINVAL. 83 84 - UV_METRICS_IDLE_TIME: Accumulate the amount of idle time the event loop 85 spends in the event provider. 86 87 This option is necessary to use :c:func:`uv_metrics_idle_time`. 88 89 - UV_LOOP_ENABLE_IO_URING_SQPOLL: Enable SQPOLL io_uring instance to handle 90 asynchronous file system operations. 91 92 .. versionchanged:: 1.39.0 added the UV_METRICS_IDLE_TIME option. 93 94 .. versionchanged:: 1.49.0 added the UV_LOOP_ENABLE_IO_URING_SQPOLL option. 95 96.. c:function:: int uv_loop_close(uv_loop_t* loop) 97 98 Releases all internal loop resources. Call this function only when the loop 99 has finished executing and all open handles and requests have been closed, 100 or it will return UV_EBUSY. After this function returns, the user can free 101 the memory allocated for the loop. 102 103.. c:function:: uv_loop_t* uv_default_loop(void) 104 105 Returns the initialized default loop. It may return NULL in case of 106 allocation failure. 107 108 This function is just a convenient way for having a global loop throughout 109 an application, the default loop is in no way different than the ones 110 initialized with :c:func:`uv_loop_init`. As such, the default loop can (and 111 should) be closed with :c:func:`uv_loop_close` so the resources associated 112 with it are freed. 113 114 .. warning:: 115 This function is not thread safe. 116 117.. c:function:: int uv_run(uv_loop_t* loop, uv_run_mode mode) 118 119 This function runs the event loop. It will act differently depending on the 120 specified mode: 121 122 - UV_RUN_DEFAULT: Runs the event loop until there are no more active and 123 referenced handles or requests. Returns non-zero if :c:func:`uv_stop` 124 was called and there are still active handles or requests. Returns 125 zero in all other cases. 126 - UV_RUN_ONCE: Poll for i/o once. Note that this function blocks if 127 there are no pending callbacks. Returns zero when done (no active handles 128 or requests left), or non-zero if more callbacks are expected (meaning 129 you should run the event loop again sometime in the future). 130 - UV_RUN_NOWAIT: Poll for i/o once but don't block if there are no 131 pending callbacks. Returns zero if done (no active handles 132 or requests left), or non-zero if more callbacks are expected (meaning 133 you should run the event loop again sometime in the future). 134 135 :c:func:`uv_run` is not reentrant. It must not be called from a callback. 136 137.. c:function:: int uv_loop_alive(const uv_loop_t* loop) 138 139 Returns non-zero if there are referenced active handles, active 140 requests or closing handles in the loop. 141 142.. c:function:: void uv_stop(uv_loop_t* loop) 143 144 Stop the event loop, causing :c:func:`uv_run` to end as soon as 145 possible. This will happen not sooner than the next loop iteration. 146 If this function was called before blocking for i/o, the loop won't block 147 for i/o on this iteration. 148 149.. c:function:: size_t uv_loop_size(void) 150 151 Returns the size of the `uv_loop_t` structure. Useful for FFI binding 152 writers who don't want to know the structure layout. 153 154.. c:function:: int uv_backend_fd(const uv_loop_t* loop) 155 156 Get backend file descriptor. Only kqueue, epoll and event ports are 157 supported. 158 159 This can be used in conjunction with `uv_run(loop, UV_RUN_NOWAIT)` to 160 poll in one thread and run the event loop's callbacks in another see 161 test/test-embed.c for an example. 162 163 .. note:: 164 Embedding a kqueue fd in another kqueue pollset doesn't work on all platforms. It's not 165 an error to add the fd but it never generates events. 166 167.. c:function:: int uv_backend_timeout(const uv_loop_t* loop) 168 169 Get the poll timeout. The return value is in milliseconds, or -1 for no 170 timeout. 171 172.. c:function:: uint64_t uv_now(const uv_loop_t* loop) 173 174 Return the current timestamp in milliseconds. The timestamp is cached at 175 the start of the event loop tick, see :c:func:`uv_update_time` for details 176 and rationale. 177 178 The timestamp increases monotonically from some arbitrary point in time. 179 Don't make assumptions about the starting point, you will only get 180 disappointed. 181 182 .. note:: 183 Use :c:func:`uv_hrtime` if you need sub-millisecond granularity. 184 185.. c:function:: void uv_update_time(uv_loop_t* loop) 186 187 Update the event loop's concept of "now". Libuv caches the current time 188 at the start of the event loop tick in order to reduce the number of 189 time-related system calls. 190 191 You won't normally need to call this function unless you have callbacks 192 that block the event loop for longer periods of time, where "longer" is 193 somewhat subjective but probably on the order of a millisecond or more. 194 195.. c:function:: void uv_walk(uv_loop_t* loop, uv_walk_cb walk_cb, void* arg) 196 197 Walk the list of handles: `walk_cb` will be executed with the given `arg`. 198 199.. c:function:: int uv_loop_fork(uv_loop_t* loop) 200 201 .. versionadded:: 1.12.0 202 203 Reinitialize any kernel state necessary in the child process after 204 a :man:`fork(2)` system call. 205 206 Previously started watchers will continue to be started in the 207 child process. 208 209 It is necessary to explicitly call this function on every event 210 loop created in the parent process that you plan to continue to 211 use in the child, including the default loop (even if you don't 212 continue to use it in the parent). This function must be called 213 before calling :c:func:`uv_run` or any other API function using 214 the loop in the child. Failure to do so will result in undefined 215 behaviour, possibly including duplicate events delivered to both 216 parent and child or aborting the child process. 217 218 When possible, it is preferred to create a new loop in the child 219 process instead of reusing a loop created in the parent. New loops 220 created in the child process after the fork should not use this 221 function. 222 223 This function is not implemented on Windows, where it returns ``UV_ENOSYS``. 224 225 .. caution:: 226 227 This function is experimental. It may contain bugs, and is subject to 228 change or removal. API and ABI stability is not guaranteed. 229 230 .. note:: 231 232 On Mac OS X, if directory FS event handles were in use in the 233 parent process *for any event loop*, the child process will no 234 longer be able to use the most efficient FSEvent 235 implementation. Instead, uses of directory FS event handles in 236 the child will fall back to the same implementation used for 237 files and on other kqueue-based systems. 238 239 .. caution:: 240 241 On AIX and SunOS, FS event handles that were already started in 242 the parent process at the time of forking will *not* deliver 243 events in the child process; they must be closed and restarted. 244 On all other platforms, they will continue to work normally 245 without any further intervention. 246 247 .. caution:: 248 249 Any previous value returned from :c:func:`uv_backend_fd` is now 250 invalid. That function must be called again to determine the 251 correct backend file descriptor. 252 253.. c:function:: void* uv_loop_get_data(const uv_loop_t* loop) 254 255 Returns `loop->data`. 256 257 .. versionadded:: 1.19.0 258 259.. c:function:: void uv_loop_set_data(uv_loop_t* loop, void* data) 260 261 Sets `loop->data` to `data`. 262 263 .. versionadded:: 1.19.0 264
