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