Mercurial

comparison third_party/libuv/docs/src/loop.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
1
2 .. _loop:
3
4 :c:type:`uv_loop_t` --- Event loop
5 ==================================
6
7 The event loop is the central part of libuv's functionality. It takes care
8 of polling for i/o and scheduling callbacks to be run based on different sources
9 of events.
10
11
12 Data 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
49 Public 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
58 API
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