src/util/verto/verto.h

   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 typedef pid_t verto_proc;
  37 typedef int verto_proc_status;
  38 #endif
  39
  40 #define VERTO_SIG_IGN ((verto_callback *) 1)
  41
  42 typedef struct _verto_ctx verto_ctx;
  43 typedef struct _verto_ev verto_ev;
  44
  45 typedef enum {
  46     VERTO_EV_TYPE_NONE = 0,
  47     VERTO_EV_TYPE_IO = 1,
  48     VERTO_EV_TYPE_TIMEOUT = 1 << 1,
  49     VERTO_EV_TYPE_IDLE = 1 << 2,
  50     VERTO_EV_TYPE_SIGNAL = 1 << 3,
  51     VERTO_EV_TYPE_CHILD = 1 << 4
  52 } verto_ev_type;
  53
  54 typedef enum {
  55     VERTO_EV_FLAG_NONE = 0,
  56     VERTO_EV_FLAG_PERSIST = 1,
  57     VERTO_EV_FLAG_PRIORITY_LOW = 1 << 1,
  58     VERTO_EV_FLAG_PRIORITY_MEDIUM = 1 << 2,
  59     VERTO_EV_FLAG_PRIORITY_HIGH = 1 << 3,
  60     VERTO_EV_FLAG_IO_READ = 1 << 4,
  61     VERTO_EV_FLAG_IO_WRITE = 1 << 5,
  62     VERTO_EV_FLAG_REINITIABLE = 1 << 6,
  63     _VERTO_EV_FLAG_MAX = VERTO_EV_FLAG_REINITIABLE
  64 } verto_ev_flag;
  65
  66 typedef void (verto_callback)(verto_ctx *ctx, verto_ev *ev);
  67
  68 /**
  69  * Creates a new event context using an optionally specified implementation
  70  * and/or optionally specified required features.
  71  *
  72  * If you are an application that has already decided on using a particular
  73  * event loop implementation, you should not call this function, but instead
  74  * import the verto-NAME.h header and link against the verto-NAME.so, where
  75  * NAME is the implementation you wish to use.
  76  *
  77  * If you are a library, you should generally avoid creating event contexts
  78  * on your own but allow applications to pass in a verto_ctx you can use.
  79  *
  80  * There are two cases where you should use this function.  The first is
  81  * where you have a need to choose an implementation at run time, usually
  82  * for testing purposes.  The second and more common is when you simply
  83  * wish to remain implementation agnostic.  In this later case, you should
  84  * always call like this: verto_new(NULL, ...).  This lets verto choose the best
  85  * implementation to use.
  86  *
  87  * If impl is not NULL, a new context is returned which is backed by the
  88  * implementation specified. If the implementation specified is not
  89  * available or if the required types (reqtypes) are not provided by the
  90  * named implementation, NULL is returned. The parameter 'impl' can specify:
  91  *   * The full path to an implementation library
  92  *   * The name of the implementation library (i.e. - "glib" or "libev")
  93  *
  94  * If impl is NULL, verto will attempt to automatically determine the
  95  * best implementation to use.
  96  *
  97  * First, verto will attempt to use an existing, previously loaded
  98  * implementation. This is handled automatically by internal caching of either
  99  * the first implementation loaded or the one specified by verto_set_default().
 100  *
 101  * Second, verto will attempt to discern if you are already linked to any
 102  * of the supported implementations (to avoid wasting memory by loading
 103  * extra unnecessary libraries).  If you are linked to one supported
 104  * implementation, that implementation will be chosen.  If you are linked
 105  * to more than one supported implementation one of the ones linked to
 106  * will be chosen, but the order of the particular choice is undefined.
 107  *
 108  * Third, verto will attempt to load the compile-time default, if defined at
 109  * build time and available at runtime.
 110  *
 111  * Last, verto will attempt to load any implementation installed. The specific
 112  * order of this step is undefined.
 113  *
 114  * In all cases above, if the implementation does not support all the specified
 115  * features (reqtypes), it will be skipped and processing will continue from
 116  * where it left off. This means that if verto_new() returns non-NULL it is
 117  * guaranteed to support the features you specified.
 118  *
 119  * @see verto_set_default()
 120  * @param impl The implementation to use, or NULL.
 121  * @param reqtypes A bitwise or'd list of required event type features.
 122  * @return A new _ev_ctx, or NULL on error.  Call verto_free() when done.
 123  */
 124 verto_ctx *
 125 verto_new(const char *impl, verto_ev_type reqtypes);
 126
 127 /**
 128  * Gets the default event context using an optionally specified implementation.
 129  *
 130  * This function is essentially a singleton version of verto_new().  However,
 131  * since this function must return the same loop as the *_default() call of
 132  * the underlying implementation (if such a function exists), it is NOT a
 133  * global singleton, but a per-implementation singleton. For this reason, you
 134  * must call verto_free() when you are done with this loop. Even after calling
 135  * verto_free() on the default verto_ctx, you can safely call verto_default()
 136  * again and receive a new reference to the same (internally default) loop.
 137  *
 138  * In all other respects, verto_default() acts exactly like verto_new().
 139  *
 140  * @see verto_new()
 141  * @see verto_free()
 142  * @param impl The implementation to use, or NULL.
 143  * @param reqtypes A bitwise or'd list of required event type features.
 144  * @return The default _ev_ctx, or NULL on error.  Call verto_free() when done.
 145  */
 146 verto_ctx *
 147 verto_default(const char *impl, verto_ev_type reqtypes);
 148
 149 /**
 150  * Sets the default implementation to use by its name.
 151  *
 152  * This function returns 1 on success and 0 on failure.  It can fail for the
 153  * following reasons:
 154  *   1. The default implementation was already set via verto_set_default().
 155  *   2. The implementation specified could not be found.
 156  *   3. The implementation specified didn't support the features specified.
 157  *   4. The impl argument was NULL.
 158  *   5. verto_new() was already called.
 159  *   6. verto_default() was already called.
 160  *   7. verto_new_NAME() was already called.
 161  *   8. verto_default_NAME() was already called.
 162  *   9. verto_convert_NAME() was already called.
 163  *
 164  * @see verto_new()
 165  * @see verto_default()
 166  * @param impl The implementation to use.
 167  * @param reqtypes A bitwise or'd list of required event type features.
 168  * @return The default _ev_ctx, or NULL on error.  Call verto_free() when done.
 169  */
 170 int
 171 verto_set_default(const char *impl, verto_ev_type reqtypes);
 172
 173 /**
 174  * Frees a verto_ctx.
 175  *
 176  * When called on a default verto_ctx, the reference will be freed but the
 177  * internal default loop will still be available via another call to
 178  * verto_default().
 179  *
 180  * @see verto_new()
 181  * @see verto_default()
 182  * @param ctx The verto_ctx to free.
 183  */
 184 void
 185 verto_free(verto_ctx *ctx);
 186
 187 /**
 188  * Run the verto_ctx forever, or at least until verto_break() is called.
 189  *
 190  * @see verto_break()
 191  * @param ctx The verto_ctx to run.
 192  */
 193 void
 194 verto_run(verto_ctx *ctx);
 195
 196 /**
 197  * Run the verto_ctx once. May block.
 198  *
 199  * @param ctx The verto_ctx to run once.
 200  */
 201 void
 202 verto_run_once(verto_ctx *ctx);
 203
 204 /**
 205  * Exits the currently running verto_ctx.
 206  *
 207  * @see verto_run()
 208  * @param ctx The verto_ctx to exit.
 209  */
 210 void
 211 verto_break(verto_ctx *ctx);
 212
 213 /**
 214  * Re-initializes the verto_ctx.
 215  *
 216  * This function deletes all events, except those which have set the
 217  * VERTO_EV_FLAG_REINITIABLE flag. If you fork(), you MUST call this in the
 218  * child process after the fork!
 219  *
 220  * @see verto_new()
 221  * @see verto_default()
 222  * @param ctx The verto_ctx to re-initialize.
 223  */
 224 void
 225 verto_reinitialize(verto_ctx *ctx);
 226
 227 /**
 228  * Adds a callback executed when a file descriptor is ready to be read/written.
 229  *
 230  * All verto_ev events are automatically freed when their parent verto_ctx is
 231  * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
 232  * provided, the event will repeat until verto_del() is called. If
 233  * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
 234  * after its execution. In either case, you may call verto_del() at any time
 235  * to prevent the event from executing.
 236  *
 237  * NOTE: On Windows, the underlying select() only works with sockets. As such,
 238  * any attempt to add a non-socket io event on Windows will produce undefined
 239  * results and may even crash.
 240  *
 241  * @see verto_del()
 242  * @param ctx The verto_ctx which will fire the callback.
 243  * @param flags The flags to set (at least one VERTO_EV_FLAG_IO* required).
 244  * @param callback The callback to fire.
 245  * @param fd The file descriptor to watch for reads.
 246  * @return The verto_ev registered with the event context or NULL on error.
 247  */
 248 verto_ev *
 249 verto_add_io(verto_ctx *ctx, verto_ev_flag flags,
 250              verto_callback *callback, int fd);
 251
 252 /**
 253  * Adds a callback executed after a period of time.
 254  *
 255  * All verto_ev events are automatically freed when their parent verto_ctx is
 256  * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
 257  * provided, the event will repeat until verto_del() is called. If
 258  * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
 259  * after its execution. In either case, you may call verto_del() at any time
 260  * to prevent the event from executing.
 261  *
 262  * @see verto_del()
 263  * @param ctx The verto_ctx which will fire the callback.
 264  * @param flags The flags to set.
 265  * @param callback The callback to fire.
 266  * @param interval Time period to wait before firing (in milliseconds).
 267  * @return The verto_ev registered with the event context.
 268  */
 269 verto_ev *
 270 verto_add_timeout(verto_ctx *ctx, verto_ev_flag flags,
 271                   verto_callback *callback, time_t interval);
 272
 273 /**
 274  * Adds a callback executed when there is nothing else to do.
 275  *
 276  * All verto_ev events are automatically freed when their parent verto_ctx is
 277  * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
 278  * provided, the event will repeat until verto_del() is called. If
 279  * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
 280  * after its execution. In either case, you may call verto_del() at any time
 281  * to prevent the event from executing.
 282  *
 283  * @see verto_del()
 284  * @param ctx The verto_ctx which will fire the callback.
 285  * @param flags The flags to set.
 286  * @param callback The callback to fire.
 287  * @return The verto_ev registered with the event context.
 288  */
 289 verto_ev *
 290 verto_add_idle(verto_ctx *ctx, verto_ev_flag flags,
 291                verto_callback *callback);
 292
 293 /**
 294  * Adds a callback executed when a signal is received.
 295  *
 296  * All verto_ev events are automatically freed when their parent verto_ctx is
 297  * freed. You do not need to free them manually. If VERTO_EV_FLAG_PERSIST is
 298  * provided, the event will repeat until verto_del() is called. If
 299  * VERTO_EV_FLAG_PERSIST is not provided, the event will be freed automatically
 300  * after its execution. In either case, you may call verto_del() at any time
 301  * to prevent the event from executing.
 302  *
 303  * NOTE: If you attempt to ignore a signal without the VERTO_EV_FLAG_PERSIST
 304  * flag, this function fails.
 305  *
 306  * NOTE: SIGCHLD is expressly not supported. If you want this notification,
 307  * please use verto_add_child().
 308  *
 309  * WARNNIG: Signal events can only be reliably received in the default _ev_ctx
 310  * in some implementations.  Attempting to receive signal events in non-default
 311  * loops may result in assert() failures.
 312  *
 313  * WARNING: While verto does its best to protect you from crashes, there is
 314  * essentially no way to do signal events if you mix multiple implementations in
 315  * a single process. Attempting to do so will result in undefined behavior,
 316  * and potentially even a crash. You have been warned.
 317  *
 318  * @see verto_add_child()
 319  * @see verto_repeat()
 320  * @see verto_del()
 321  * @param ctx The verto_ctx which will fire the callback.
 322  * @param flags The flags to set.
 323  * @param callback The callback to fire.
 324  * @param signal The signal to watch for.
 325  * @return The verto_ev registered with the event context.
 326  */
 327 verto_ev *
 328 verto_add_signal(verto_ctx *ctx, verto_ev_flag flags,
 329                  verto_callback *callback, int signal);
 330
 331 /**
 332  * Adds a callback executed when a child process exits.
 333  *
 334  * This event will be freed automatically after its execution. Due to the
 335  * nature of a process' life-cycle, child events cannot persist (processes only
 336  * exit once). This function returns NULL if you attempt to use
 337  * VERTO_EV_FLAG_PERSIST. You may, of course, call verto_del() at any time to
 338  * prevent the callback from firing.
 339  *
 340  * @see verto_del()
 341  * @param ctx The verto_ctx which will fire the callback.
 342  * @param flags The flags to set.
 343  * @param callback The callback to fire.
 344  * @param child The pid (POSIX) or handle (Win32) of the child to watch for.
 345  * @return The verto_ev registered with the event context.
 346  */
 347 verto_ev *
 348 verto_add_child(verto_ctx *ctx, verto_ev_flag flags,
 349                 verto_callback *callback, verto_proc proc);
 350
 351 /**
 352  * Sets the private pointer of the verto_ev.
 353  *
 354  * The free callback will be called in two cases:
 355  *   1. When the event is deleted (manually or automatically)
 356  *   2. When verto_set_private() is called again, unless
 357  *      free is NULL.
 358  *
 359  * @see verto_get_private()
 360  * @param ev The verto_ev
 361  * @param priv The private value to store
 362  * @param free The callback used to free the data or NULL
 363  */
 364 void
 365 verto_set_private(verto_ev *ev, void *priv, verto_callback *free);
 366
 367 /**
 368  * Gets the private pointer of the verto_ev.
 369  *
 370  * @see verto_set_private()
 371  * @param ev The verto_ev
 372  * @return The verto_ev private pointer
 373  */
 374 void *
 375 verto_get_private(const verto_ev *ev);
 376
 377 /**
 378  * Gets the type of the verto_ev.
 379  *
 380  * @see verto_add_io()
 381  * @see verto_add_timeout()
 382  * @see verto_add_idle()
 383  * @see verto_add_signal()
 384  * @see verto_add_child()
 385  * @param ev The verto_ev
 386  * @return The verto_ev type
 387  */
 388 verto_ev_type
 389 verto_get_type(const verto_ev *ev);
 390
 391 /**
 392  * Gets the flags associated with the given verto_ev.
 393  *
 394  * @see verto_add_io()
 395  * @see verto_add_timeout()
 396  * @see verto_add_idle()
 397  * @see verto_add_signal()
 398  * @see verto_add_child()
 399  * @param ev The verto_ev
 400  * @return The verto_ev type
 401  */
 402 verto_ev_flag
 403 verto_get_flags(const verto_ev *ev);
 404
 405 /**
 406  * Gets the file descriptor associated with a read/write verto_ev.
 407  *
 408  * @see verto_add_io()
 409  * @param ev The verto_ev to retrieve the file descriptor from.
 410  * @return The file descriptor, or -1 if not a read/write event.
 411  */
 412 int
 413 verto_get_fd(const verto_ev *ev);
 414
 415 /**
 416  * Gets the interval associated with a timeout verto_ev.
 417  *
 418  * @see verto_add_timeout()
 419  * @param ev The verto_ev to retrieve the interval from.
 420  * @return The interval, or 0 if not a timeout event.
 421  */
 422 time_t
 423 verto_get_interval(const verto_ev *ev);
 424
 425 /**
 426  * Gets the signal associated with a signal verto_ev.
 427  *
 428  * @see verto_add_signal()
 429  * @param ev The verto_ev to retrieve the signal from.
 430  * @return The signal, or -1 if not a signal event.
 431  */
 432 int
 433 verto_get_signal(const verto_ev *ev);
 434
 435 /**
 436  * Gets the process associated with a child verto_ev.
 437  *
 438  * @see verto_add_child()
 439  * @param ev The verto_ev to retrieve the process from.
 440  * @return The pid/handle, or 0/NULL if not a child event (POSIX/Win32).
 441  */
 442 verto_proc
 443 verto_get_proc(const verto_ev *ev);
 444
 445 /**
 446  * Gets the status of the process which caused this event to fire.
 447  *
 448  * @see verto_add_child()
 449  * @param ev The verto_ev to retrieve the status from.
 450  * @return The pid/handle status.
 451  */
 452 verto_proc_status
 453 verto_get_proc_status(const verto_ev *ev);
 454
 455 /**
 456  * Removes an event from from the event context and frees it.
 457  *
 458  * The event and its contents cannot be used after this call.
 459  *
 460  * @see verto_add_io()
 461  * @see verto_add_timeout()
 462  * @see verto_add_idle()
 463  * @see verto_add_signal()
 464  * @see verto_add_child()
 465  * @param ev The event to delete.
 466  */
 467 void
 468 verto_del(verto_ev *ev);
 469
 470 /**
 471  * Returns the event types supported by this implementation.
 472  *
 473  * @param ctx The verto_ctx to query.
 474  * @return The event types supported.
 475  */
 476 verto_ev_type
 477 verto_get_supported_types(verto_ctx *ctx);
 478
 479 #endif /* VERTO_H_ */