Mercurial > repos > rliterman > csp2

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