Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/verto.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
1 /*
2 * Copyright 2011 Red Hat, Inc.
3 *
4 * Permission is hereby granted, free of charge, to any person
5 * obtaining a copy of this software and associated documentation files
6 * (the "Software"), to deal in the Software without restriction,
7 * including without limitation the rights to use, copy, modify, merge,
8 * publish, distribute, sublicense, and/or sell copies of the Software,
9 * and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25 #ifndef VERTO_H_
26 #define VERTO_H_
27
28 #include <time.h> /* For time_t */
29 #include <unistd.h> /* For pid_t */
30
31 #ifdef WIN32
32 #include <windows.h>
33 typedef HANDLE verto_proc;
34 typedef DWORD verto_proc_status;
35 #else
36 #include <sys/types.h>
37 typedef pid_t verto_proc;
38 typedef int verto_proc_status;
39 #endif
40
41 #define VERTO_SIG_IGN ((verto_callback *) 1)
42
43 #ifdef __cplusplus
44 extern "C"
45 {
46 #endif /* __cplusplus */
47
48 typedef struct verto_ctx verto_ctx;
49 typedef struct verto_ev verto_ev;
50
51 typedef enum {
52 VERTO_EV_TYPE_NONE = 0,
53 VERTO_EV_TYPE_IO = 1,
54 VERTO_EV_TYPE_TIMEOUT = 1 << 1,
55 VERTO_EV_TYPE_IDLE = 1 << 2,
56 VERTO_EV_TYPE_SIGNAL = 1 << 3,
57 VERTO_EV_TYPE_CHILD = 1 << 4
58 } verto_ev_type;
59
60 typedef enum {
61 VERTO_EV_FLAG_NONE = 0,
62 VERTO_EV_FLAG_PERSIST = 1,
63 VERTO_EV_FLAG_PRIORITY_LOW = 1 << 1,
64 VERTO_EV_FLAG_PRIORITY_MEDIUM = 1 << 2,
65 VERTO_EV_FLAG_PRIORITY_HIGH = 1 << 3,
66 VERTO_EV_FLAG_IO_READ = 1 << 4,
67 VERTO_EV_FLAG_IO_WRITE = 1 << 5,
68 VERTO_EV_FLAG_IO_ERROR = 1 << 7,
69 VERTO_EV_FLAG_IO_CLOSE_FD = 1 << 8,
70 VERTO_EV_FLAG_REINITIABLE = 1 << 6,
71 _VERTO_EV_FLAG_MUTABLE_MASK = VERTO_EV_FLAG_PRIORITY_LOW
72 | VERTO_EV_FLAG_PRIORITY_MEDIUM
73 | VERTO_EV_FLAG_PRIORITY_HIGH
74 | VERTO_EV_FLAG_IO_READ
75 | VERTO_EV_FLAG_IO_WRITE,
76 _VERTO_EV_FLAG_MAX = VERTO_EV_FLAG_IO_CLOSE_FD
77 } verto_ev_flag;
78
79 typedef void (verto_callback)(verto_ctx *ctx, verto_ev *ev);
80
81 /**
82 * Creates a new event context using an optionally specified implementation
83 * and/or optionally specified required features.
84 *
85 * If you are an application that has already decided on using a particular
86 * event loop implementation, you should not call this function, but instead
87 * import the verto-NAME.h header and link against the verto-NAME.so, where
88 * NAME is the implementation you wish to use.
89 *
90 * If you are a library, you should generally avoid creating event contexts
91 * on your own but allow applications to pass in a verto_ctx you can use.
92 *
93 * There are two cases where you should use this function. The first is
94 * where you have a need to choose an implementation at run time, usually
95 * for testing purposes. The second and more common is when you simply
96 * wish to remain implementation agnostic. In this later case, you should
97 * always call like this: verto_new(NULL, ...). This lets verto choose the best
98 * implementation to use.
99 *
100 * If impl is not NULL, a new context is returned which is backed by the
101 * implementation specified. If the implementation specified is not
102 * available or if the required types (reqtypes) are not provided by the
103 * named implementation, NULL is returned. The parameter 'impl' can specify:
104 * * The full path to an implementation library
105 * * The name of the implementation library (i.e. - "glib" or "libev")
106 *
107 * If impl is NULL, verto will attempt to automatically determine the
108 * best implementation to use.
109 *
110 * First, verto will attempt to use an existing, previously loaded
111 * implementation. This is handled automatically by internal caching of either
112 * the first implementation loaded or the one specified by verto_set_default().
113 *
114 * Second, verto will attempt to discern if you are already linked to any
115 * of the supported implementations (to avoid wasting memory by loading
116 * extra unnecessary libraries). If you are linked to one supported
117 * implementation, that implementation will be chosen. If you are linked
118 * to more than one supported implementation one of the ones linked to
119 * will be chosen, but the order of the particular choice is undefined.
120 *
121 * Third, verto will attempt to load the compile-time default, if defined at
122 * build time and available at runtime.
123 *
124 * Last, verto will attempt to load any implementation installed. The specific
125 * order of this step is undefined.
126 *
127 * In all cases above, if the implementation does not support all the specified
128 * features (reqtypes), it will be skipped and processing will continue from
129 * where it left off. This means that if verto_new() returns non-NULL it is
130 * guaranteed to support the features you specified.
131 *
132 * @see verto_set_default()
133 * @param impl The implementation to use, or NULL.
134 * @param reqtypes A bitwise or'd list of required event type features.
135 * @return A new verto_ctx, or NULL on error. Call verto_free() when done.
136 */
137 verto_ctx *
138 verto_new(const char *impl, verto_ev_type reqtypes);
139
140 /**
141 * Gets the default event context using an optionally specified implementation.
142 *
143 * This function is essentially a singleton version of verto_new(). However,
144 * since this function must return the same loop as the *_default() call of
145 * the underlying implementation (if such a function exists), it is NOT a
146 * global singleton, but a per-implementation singleton. For this reason, you
147 * must call verto_free() when you are done with this loop. Even after calling
148 * verto_free() on the default verto_ctx, you can safely call verto_default()
149 * again and receive a new reference to the same (internally default) loop.
150 *
151 * In all other respects, verto_default() acts exactly like verto_new().
152 *
153 * @see verto_new()
154 * @see verto_free()
155 * @param impl The implementation to use, or NULL.
156 * @param reqtypes A bitwise or'd list of required event type features.
157 * @return The default verto_ctx, or NULL on error. Call verto_free() when done.
158 */
159 verto_ctx *
160 verto_default(const char *impl, verto_ev_type reqtypes);
161
162 /**
163 * Sets the default implementation to use by its name.
164 *
165 * This function returns 1 on success and 0 on failure. It can fail for the
166 * following reasons:
167 * 1. The default implementation was already set via verto_set_default().
168 * 2. The implementation specified could not be found.
169 * 3. The implementation specified didn't support the features specified.
170 * 4. The impl argument was NULL.
171 * 5. verto_new() was already called.
172 * 6. verto_default() was already called.
173 * 7. verto_new_NAME() was already called.
174 * 8. verto_default_NAME() was already called.
175 * 9. verto_convert_NAME() was already called.
176 *
177 * @see verto_new()
178 * @see verto_default()
179 * @param impl The implementation to use.
180 * @param reqtypes A bitwise or'd list of required event type features.
181 * @return The default verto_ctx, or NULL on error. Call verto_free() when done.
182 */
183 int
184 verto_set_default(const char *impl, verto_ev_type reqtypes);
185
186 /**
187 * Sets the allocator to use for verto_ctx and verto_ev objects.
188 *
189 * If you plan to set the allocator, you MUST call this function before any
190 * other verto_*() calls.
191 *
192 * @see verto_new()
193 * @see verto_default()
194 * @see verto_add_io()
195 * @see verto_add_timeout()
196 * @see verto_add_idle()
197 * @see verto_add_signal()
198 * @see verto_add_child()
199 * @param resize The allocator to use (behaves like realloc();
200 * resize(ptr, 0) must free memory at ptr.)
201 * @param hierarchical Zero if the allocator is not hierarchical
202 */
203 int
204 verto_set_allocator(void *(*resize)(void *mem, size_t size), int hierarchical);
205
206 /**
207 * Frees a verto_ctx.
208 *
209 * When called on a default verto_ctx, the reference will be freed but the
210 * internal default loop will still be available via another call to
211 * verto_default().
212 *
213 * @see verto_new()
214 * @see verto_default()
215 * @param ctx The verto_ctx to free.
216 */
217 void
218 verto_free(verto_ctx *ctx);
219
220 /**
221 * Frees global state.
222 *
223 * Remove and free all allocated global state. Call only when no further
224 * contexts exist and all threads have exited.
225 *
226 * @see verto_new()
227 * @see verto_free()
228 * @see verto_default()
229 */
230 void
231 verto_cleanup(void);
232
233 /**
234 * Run the verto_ctx forever, or at least until verto_break() is called.
235 *
236 * @see verto_break()
237 * @param ctx The verto_ctx to run.
238 */
239 void
240 verto_run(verto_ctx *ctx);
241
242 /**
243 * Run the verto_ctx once. May block.
244 *
245 * @param ctx The verto_ctx to run once.
246 */
247 void
248 verto_run_once(verto_ctx *ctx);
249
250 /**
251 * Exits the currently running verto_ctx.
252 *
253 * @see verto_run()
254 * @param ctx The verto_ctx to exit.
255 */
256 void
257 verto_break(verto_ctx *ctx);
258
259 /**
260 * Re-initializes the verto_ctx.
261 *
262 * This function deletes all events, except those which have set the
263 * VERTO_EV_FLAG_REINITIABLE flag. If you fork(), you MUST call this in the
264 * child process after the fork!
265 *
266 * If this function fails it indicates that at least one
267 * VERTO_EV_FLAG_REINITIABLE event was not rearmed or that ctx was NULL.
268 *
269 * @see verto_new()
270 * @see verto_default()
271 * @param ctx The verto_ctx to re-initialize.
272 * @return Non-zero on success, 0 on error.
273 */
274 int
275 verto_reinitialize(verto_ctx *ctx);
276
277 /**
278 * Adds a callback executed when a file descriptor is ready to be read/written.
279 *
280 * All verto_ev events are automatically freed when their parent verto_ctx is
281 * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
282 * provided, the event will repeat until verto_del() is called. If
283 * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
284 * after its execution. In either case, you may call verto_del() at any time
285 * to prevent the event from executing.
286 * If VERTO_EV_FLAG_IO_CLOSE_FD is provided the passed in fd is automatically
287 * closed when the event is freed with verto_del()
288 *
289 * NOTE: On Windows, the underlying select() only works with sockets. As such,
290 * any attempt to add a non-socket io event on Windows will produce undefined
291 * results and may even crash.
292 *
293 * @see verto_del()
294 * @param ctx The verto_ctx which will fire the callback.
295 * @param flags The flags to set (at least one VERTO_EV_FLAG_IO* required).
296 * @param callback The callback to fire.
297 * @param fd The file descriptor to watch for reads.
298 * @return The verto_ev registered with the event context or NULL on error.
299 */
300 verto_ev *
301 verto_add_io(verto_ctx *ctx, verto_ev_flag flags,
302 verto_callback *callback, int fd);
303
304 /**
305 * Adds a callback executed after a period of time.
306 *
307 * All verto_ev events are automatically freed when their parent verto_ctx is
308 * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
309 * provided, the event will repeat until verto_del() is called. If
310 * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
311 * after its execution. In either case, you may call verto_del() at any time
312 * to prevent the event from executing.
313 *
314 * @see verto_del()
315 * @param ctx The verto_ctx which will fire the callback.
316 * @param flags The flags to set.
317 * @param callback The callback to fire.
318 * @param interval Time period to wait before firing (in milliseconds).
319 * @return The verto_ev registered with the event context.
320 */
321 verto_ev *
322 verto_add_timeout(verto_ctx *ctx, verto_ev_flag flags,
323 verto_callback *callback, time_t interval);
324
325 /**
326 * Adds a callback executed when there is nothing else to do.
327 *
328 * All verto_ev events are automatically freed when their parent verto_ctx is
329 * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
330 * provided, the event will repeat until verto_del() is called. If
331 * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
332 * after its execution. In either case, you may call verto_del() at any time
333 * to prevent the event from executing.
334 *
335 * @see verto_del()
336 * @param ctx The verto_ctx which will fire the callback.
337 * @param flags The flags to set.
338 * @param callback The callback to fire.
339 * @return The verto_ev registered with the event context.
340 */
341 verto_ev *
342 verto_add_idle(verto_ctx *ctx, verto_ev_flag flags,
343 verto_callback *callback);
344
345 /**
346 * Adds a callback executed when a signal is received.
347 *
348 * All verto_ev events are automatically freed when their parent verto_ctx is
349 * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
350 * provided, the event will repeat until verto_del() is called. If
351 * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
352 * after its execution. In either case, you may call verto_del() at any time
353 * to prevent the event from executing.
354 *
355 * NOTE: If you attempt to ignore a signal without the VERTO_EV_FLAG_PERSIST
356 * flag, this function fails.
357 *
358 * NOTE: SIGCHLD is expressly not supported. If you want this notification,
359 * please use verto_add_child().
360 *
361 * WARNNIG: Signal events can only be reliably received in the default verto_ctx
362 * in some implementations. Attempting to receive signal events in non-default
363 * loops may result in assert() failures.
364 *
365 * WARNING: While verto does its best to protect you from crashes, there is
366 * essentially no way to do signal events if you mix multiple implementations in
367 * a single process. Attempting to do so will result in undefined behavior,
368 * and potentially even a crash. You have been warned.
369 *
370 * @see verto_add_child()
371 * @see verto_repeat()
372 * @see verto_del()
373 * @param ctx The verto_ctx which will fire the callback.
374 * @param flags The flags to set.
375 * @param callback The callback to fire.
376 * @param signal The signal to watch for.
377 * @return The verto_ev registered with the event context.
378 */
379 verto_ev *
380 verto_add_signal(verto_ctx *ctx, verto_ev_flag flags,
381 verto_callback *callback, int signal);
382
383 /**
384 * Adds a callback executed when a child process exits.
385 *
386 * This event will be freed automatically after its execution. Due to the
387 * nature of a process' life-cycle, child events cannot persist (processes only
388 * exit once). This function returns NULL if you attempt to use
389 * VERTO_EV_FLAG_PERSIST. You may, of course, call verto_del() at any time to
390 * prevent the callback from firing.
391 *
392 * @see verto_del()
393 * @param ctx The verto_ctx which will fire the callback.
394 * @param flags The flags to set.
395 * @param callback The callback to fire.
396 * @param child The pid (POSIX) or handle (Win32) of the child to watch for.
397 * @return The verto_ev registered with the event context.
398 */
399 verto_ev *
400 verto_add_child(verto_ctx *ctx, verto_ev_flag flags,
401 verto_callback *callback, verto_proc proc);
402
403 /**
404 * Sets the private pointer of the verto_ev.
405 *
406 * The free callback will be called in two cases:
407 * 1. When the event is deleted (manually or automatically)
408 * 2. When verto_set_private() is called again, unless
409 * free is NULL.
410 *
411 * @see verto_get_private()
412 * @param ev The verto_ev
413 * @param priv The private value to store
414 * @param free The callback used to free the data or NULL
415 */
416 void
417 verto_set_private(verto_ev *ev, void *priv, verto_callback *free);
418
419 /**
420 * Gets the private pointer of the verto_ev.
421 *
422 * @see verto_set_private()
423 * @param ev The verto_ev
424 * @return The verto_ev private pointer
425 */
426 void *
427 verto_get_private(const verto_ev *ev);
428
429 /**
430 * Gets the type of the verto_ev.
431 *
432 * @see verto_add_io()
433 * @see verto_add_timeout()
434 * @see verto_add_idle()
435 * @see verto_add_signal()
436 * @see verto_add_child()
437 * @param ev The verto_ev
438 * @return The verto_ev type
439 */
440 verto_ev_type
441 verto_get_type(const verto_ev *ev);
442
443 /**
444 * Gets the flags associated with the given verto_ev.
445 *
446 * @see verto_add_io()
447 * @see verto_add_timeout()
448 * @see verto_add_idle()
449 * @see verto_add_signal()
450 * @see verto_add_child()
451 * @see verto_set_flags()
452 * @param ev The verto_ev
453 * @return The verto_ev type
454 */
455 verto_ev_flag
456 verto_get_flags(const verto_ev *ev);
457
458 /**
459 * Sets the flags associated with the given verto_ev.
460 *
461 * See _VERTO_EV_FLAG_MUTABLE_MASK for the flags that can be changed
462 * with this function. All others will be ignored. If the flags specified
463 * are the same as the flags the event already has, this function is a no-op.
464 *
465 * @see verto_add_io()
466 * @see verto_add_timeout()
467 * @see verto_add_idle()
468 * @see verto_add_signal()
469 * @see verto_add_child()
470 * @see verto_get_flags()
471 * @param ev The verto_ev
472 * @param flags The flags for the event
473 */
474 void
475 verto_set_flags(verto_ev *ev, verto_ev_flag flags);
476
477 /**
478 * Gets the file descriptor associated with a read/write verto_ev.
479 *
480 * @see verto_add_io()
481 * @param ev The verto_ev to retrieve the file descriptor from.
482 * @return The file descriptor, or -1 if not a read/write event.
483 */
484 int
485 verto_get_fd(const verto_ev *ev);
486
487 /**
488 * Gets the file descriptor state from when the event fires.
489 *
490 * @see verto_add_io()
491 * @param ev The verto_ev to retrieve the fd state from.
492 * @return The fd state.
493 */
494 verto_ev_flag
495 verto_get_fd_state(const verto_ev *ev);
496
497 /**
498 * Gets the interval associated with a timeout verto_ev.
499 *
500 * @see verto_add_timeout()
501 * @param ev The verto_ev to retrieve the interval from.
502 * @return The interval, or 0 if not a timeout event.
503 */
504 time_t
505 verto_get_interval(const verto_ev *ev);
506
507 /**
508 * Gets the signal associated with a signal verto_ev.
509 *
510 * @see verto_add_signal()
511 * @param ev The verto_ev to retrieve the signal from.
512 * @return The signal, or -1 if not a signal event.
513 */
514 int
515 verto_get_signal(const verto_ev *ev);
516
517 /**
518 * Gets the process associated with a child verto_ev.
519 *
520 * @see verto_add_child()
521 * @param ev The verto_ev to retrieve the process from.
522 * @return The pid/handle, or 0/NULL if not a child event (POSIX/Win32).
523 */
524 verto_proc
525 verto_get_proc(const verto_ev *ev);
526
527 /**
528 * Gets the status of the process which caused this event to fire.
529 *
530 * @see verto_add_child()
531 * @param ev The verto_ev to retrieve the status from.
532 * @return The pid/handle status.
533 */
534 verto_proc_status
535 verto_get_proc_status(const verto_ev *ev);
536
537 /**
538 * Gets the verto_ctx associated with a verto_ev.
539 *
540 * This is a borrowed reference, don't attempt to free it!
541 *
542 * @param ev The verto_ev to retrieve the verto_ctx from.
543 * @return The verto_ctx.
544 */
545 verto_ctx *
546 verto_get_ctx(const verto_ev *ev);
547
548 /**
549 * Removes an event from from the event context and frees it.
550 *
551 * The event and its contents cannot be used after this call.
552 *
553 * @see verto_add_io()
554 * @see verto_add_timeout()
555 * @see verto_add_idle()
556 * @see verto_add_signal()
557 * @see verto_add_child()
558 * @param ev The event to delete.
559 */
560 void
561 verto_del(verto_ev *ev);
562
563 /**
564 * Returns the event types supported by this implementation.
565 *
566 * @param ctx The verto_ctx to query.
567 * @return The event types supported.
568 */
569 verto_ev_type
570 verto_get_supported_types(verto_ctx *ctx);
571
572 #ifdef __cplusplus
573 } /* extern "C" */
574 #endif /* __cplusplus */
575 #endif /* VERTO_H_ */