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