|
160
|
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
|
