source/include/verto-module.h

0001 /*
0002  * Copyright 2011 Red Hat, Inc.
0003  *
0004  * Permission is hereby granted, free of charge, to any person
0005  * obtaining a copy of this software and associated documentation files
0006  * (the "Software"), to deal in the Software without restriction,
0007  * including without limitation the rights to use, copy, modify, merge,
0008  * publish, distribute, sublicense, and/or sell copies of the Software,
0009  * and to permit persons to whom the Software is furnished to do so,
0010  * subject to the following conditions:
0011  *
0012  * The above copyright notice and this permission notice shall be
0013  * included in all copies or substantial portions of the Software.
0014  *
0015  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
0016  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
0017  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
0018  * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
0019  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
0020  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
0021  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
0022  * SOFTWARE.
0023  */
0024
0025 /*** THE FOLLOWING ARE FOR IMPLEMENTATION MODULES ONLY ***/
0026
0027 #ifndef VERTO_MODULE_H_
0028 #define VERTO_MODULE_H_
0029
0030 #include <verto.h>
0031
0032 #ifndef VERTO_MODULE_TYPES
0033 #define VERTO_MODULE_TYPES
0034 typedef void verto_mod_ctx;
0035 typedef void verto_mod_ev;
0036 #endif
0037
0038 #define VERTO_MODULE_VERSION 3
0039 #define VERTO_MODULE_TABLE(name) verto_module_table_ ## name
0040 #define VERTO_MODULE(name, symb, types) \
0041     static verto_ctx_funcs name ## _funcs = { \
0042         name ## _ctx_new, \
0043         name ## _ctx_default, \
0044         name ## _ctx_free, \
0045         name ## _ctx_run, \
0046         name ## _ctx_run_once, \
0047         name ## _ctx_break, \
0048         name ## _ctx_reinitialize, \
0049         name ## _ctx_set_flags, \
0050         name ## _ctx_add, \
0051         name ## _ctx_del \
0052     }; \
0053     verto_module VERTO_MODULE_TABLE(name) = { \
0054         VERTO_MODULE_VERSION, \
0055         # name, \
0056         # symb, \
0057         types, \
0058         &name ## _funcs, \
0059     }; \
0060     verto_ctx * \
0061     verto_new_ ## name() \
0062     { \
0063         return verto_convert(name, 0, NULL); \
0064     } \
0065     verto_ctx * \
0066     verto_default_ ## name() \
0067     { \
0068         return verto_convert(name, 1, NULL); \
0069     }
0070
0071 typedef struct {
0072     /* Required */ verto_mod_ctx *(*ctx_new)();
0073     /* Optional */ verto_mod_ctx *(*ctx_default)();
0074     /* Required */ void (*ctx_free)(verto_mod_ctx *ctx);
0075     /* Optional */ void (*ctx_run)(verto_mod_ctx *ctx);
0076     /* Required */ void (*ctx_run_once)(verto_mod_ctx *ctx);
0077     /* Optional */ void (*ctx_break)(verto_mod_ctx *ctx);
0078     /* Optional */ void (*ctx_reinitialize)(verto_mod_ctx *ctx);
0079     /* Optional */ void (*ctx_set_flags)(verto_mod_ctx *ctx,
0080                                          const verto_ev *ev,
0081                                          verto_mod_ev *modev);
0082     /* Required */ verto_mod_ev *(*ctx_add)(verto_mod_ctx *ctx,
0083                                             const verto_ev *ev,
0084                                             verto_ev_flag *flags);
0085     /* Required */ void (*ctx_del)(verto_mod_ctx *ctx,
0086                                    const verto_ev *ev,
0087                                    verto_mod_ev *modev);
0088 } verto_ctx_funcs;
0089
0090 typedef struct {
0091     unsigned int vers;
0092     const char *name;
0093     const char *symb;
0094     verto_ev_type types;
0095     verto_ctx_funcs *funcs;
0096 } verto_module;
0097
0098 /**
0099  * Converts an existing implementation specific loop to a verto_ctx.
0100  *
0101  * This function also sets the internal default implementation so that future
0102  * calls to verto_new(NULL) or verto_default(NULL) will use this specific
0103  * implementation if it was not already set.
0104  *
0105  * @param name The name of the module (unquoted)
0106  * @param deflt Whether the ctx is the default context or not
0107  * @param ctx The context to store
0108  * @return A new verto_ctx, or NULL on error. Call verto_free() when done.
0109  */
0110 #define verto_convert(name, deflt, ctx) \
0111         verto_convert_module(&VERTO_MODULE_TABLE(name), deflt, ctx)
0112
0113 /**
0114  * Converts an existing implementation specific loop to a verto_ctx.
0115  *
0116  * If you are a module implementation, you probably want the macro above.  This
0117  * function is generally used directly only when an application is attempting
0118  * to expose a home-grown event loop to verto.
0119  *
0120  * If deflt is non-zero and a default ctx was already defined for this module
0121  * and ctx is not NULL, than ctx will be free'd and the previously defined
0122  * default will be returned.
0123  *
0124  * If ctx is non-NULL, than the pre-existing verto_mod_ctx will be converted to
0125  * to a verto_ctx; if deflt is non-zero than this verto_mod_ctx will also be
0126  * marked as the default loop for this process. If ctx is NULL, than the
0127  * appropriate constructor will be called: either module->ctx_new() or
0128  * module->ctx_default() depending on the boolean value of deflt. If
0129  * module->ctx_default is NULL and deflt is non-zero, than module->ctx_new()
0130  * will be called and the resulting verto_mod_ctx will be utilized as the
0131  * default.
0132  *
0133  * This function also sets the internal default implementation so that future
0134  * calls to verto_new(NULL) or verto_default(NULL) will use this specific
0135  * implementation if it was not already set.
0136  *
0137  * @param name The name of the module (unquoted)
0138  * @param ctx The context private to store
0139  * @return A new verto_ctx, or NULL on error. Call verto_free() when done.
0140  */
0141 verto_ctx *
0142 verto_convert_module(const verto_module *module, int deflt, verto_mod_ctx *ctx);
0143
0144 /**
0145  * Calls the callback of the verto_ev and then frees it via verto_del().
0146  *
0147  * The verto_ev is not freed (verto_del() is not called) if it is a signal event.
0148  *
0149  * @see verto_add_read()
0150  * @see verto_add_write()
0151  * @see verto_add_timeout()
0152  * @see verto_add_idle()
0153  * @see verto_add_signal()
0154  * @see verto_add_child()
0155  * @see verto_del()
0156  * @param ev The verto_ev
0157  */
0158 void
0159 verto_fire(verto_ev *ev);
0160
0161 /**
0162  * Sets the status of the pid/handle which caused this event to fire.
0163  *
0164  * This function does nothing if the verto_ev is not a child type.
0165  *
0166  * @see verto_add_child()
0167  * @param ev The verto_ev to set the status in.
0168  * @param status The pid/handle status.
0169  */
0170 void
0171 verto_set_proc_status(verto_ev *ev, verto_proc_status status);
0172
0173 /**
0174  * Sets the state of the fd which caused this event to fire.
0175  *
0176  * This function does nothing if the verto_ev is not a io type.
0177  *
0178  * Only the flags VERTO_EV_FLAG_IO_(READ|WRITE|ERROR) are supported. All other
0179  * flags are unset.
0180  *
0181  * @see verto_add_io()
0182  * @param ev The verto_ev to set the state in.
0183  * @param state The fd state.
0184  */
0185 void
0186 verto_set_fd_state(verto_ev *ev, verto_ev_flag state);
0187
0188 #endif /* VERTO_MODULE_H_ */