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_ */ 576