1

#ifndef MODULE_H

     2

#define MODULE_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Dynamically loadable modules for use with nexus.

     8

 *

     9

 * The modules are loaded using dlopen(), and hence should be standard dynamic libraries. Modules are then "loaded" by

    10

 * resolving a `struct module_funcs` symbol called "<modname>_funcs", and then using the init func to construct a

    11

 * "context", which is then further manipulated by various other module functions.

    12

 */

    13

#include "nexus.h"

    14

#include "config.h"

    15

#include "error.h"

    16

    17

#include <sys/queue.h>

    19

    20

/**

    21

 * Information required to load/identify a module.

    22

 */

    23

struct module_info {

    24

    /** Human-readable name */

    25

    const char *name;

    26

    27

    /** Filesystem path to the .so */

    28

    const char *path;

    29

};

    30

    31

/**

    32

 * A table of (function/other) pointers defining a module's behaviour. This is dynamically resolved from the module DSO

    33

 * using the "<mod_name>_module" symbol.

    34

 */

    35

struct module_desc {

    36

    /**

    37

     * Initialize the module, returning an opaque context pointer that is stored in the module state, and supplied for

    38

     * subsequent calls. The supplied nexus arg can be used to access the global state.

    39

     *

    40

     * @param nexus a pointer to the nexus struct containing the global state

    41

     * @param ctx_ptr the context pointer should be returned via this

    42

     * @param err returned error info

    43

     */

    44

    err_t (*init) (struct nexus *nexus, void **ctx_ptr, struct error_info *err);

    45

    46

    /**

    47

     * A module may define a set of available configuration parameters for use by module_conf, by setting this to an

    48

     * array of config_option's.

    49

     *

    50

     * The handler functions will recieve the module's context pointer as their ctx argument.

    51

     */

    52

    const struct config_option *config_options;

    53

    54

    /**

    55

     * Unload the module, removing all handlers/callbacks added to the nexus' irc_client. This does not have to act

    56

     * immediately, and will still have access to all irc_* resources it had earlier, and may perform I/O to unload

    57

     * cleanly. But the unloading should complete reasonably quickly, after which all event handlers added by the

    58

     * module to the nexus' ev_base should have been removed, and resources released.

    59

     *

    60

     * @param ctx the module's context pointer as returned by init

    61

     */

    62

    err_t (*unload) (void *ctx);

    63

};

    64

    65

/**

    66

 * A loaded module.

    67

 */

    68

struct module {

    69

    /** The identifying info for the module */

    70

    struct module_info info;

    71

    72

    /** The dlopen handle */

    73

    void *handle;

    74

    75

    /** The module entry point */

    76

    struct module_desc *desc;

    77

    78

    /** The module context object */

    79

    void *ctx;

    80

    81

    /** Reference back to modules struct used to load this module */

    82

    struct modules *modules;

    83

    84

    /**

    85

     * Is the module currently being unloaded?

    86

     */

    87

    bool unloading;

    88

    89

    /** Our entry in the list of modules */

    90

    TAILQ_ENTRY(module) modules_list;

    91

};

    92

    93

/**

    94

 * A set of loaded modules, and functionality to load more

    95

 */

    96

struct modules {

    97

    /** The nexus in use */

    98

    struct nexus *nexus;

    99

   100

    /** List of loaded modules */

   101

    TAILQ_HEAD(module_ctx_modules, module) list;

   102

};

   103

   104

/**

   105

 * Possible error codes

   106

 */

   107

enum module_error_code {

   108

    _ERR_MODULE_BEGIN = _ERR_MODULE,

   109

   110

    ERR_MODULE_OPEN,        ///< dlopen() failed

   111

    ERR_MODULE_NAME,        ///< invalid module_info.name

   112

    ERR_MODULE_SYM,         ///< invalid symbol

   113

    ERR_MODULE_INIT_FUNC,   ///< invalid module_init_func_t

   114

    ERR_MODULE_CONF,        ///< value error in configuration data

   115

};

   116

   117

   118

/**

   119

 * Maximum length of a module name

   120

 */

   121

#define MODULE_NAME_MAX 24

   122

   123

/**

   124

 * Maximum length of module symbol suffix

   125

 */

   126

#define MODULE_SUFFIX_MAX 16

   127

   128

/**

   129

 * Maximum length of symbol name name, including terminating NUL

   130

 */

   131

#define MODULE_SYMBOL_MAX (MODULE_NAME_MAX + 1 + MODULE_SUFFIX_MAX + 1)

   132

   133

/**

   134

 * Create a new modules state

   135

 */

   136

err_t modules_create (struct modules **modules_ptr, struct nexus *nexus);

   137

   138

/**

   139

 * Return a module's name

   140

 */

   141

const char* module_name (struct module *module);

   142

   143

/**

   144

 * Load a new module

   145

 *

   146

 * @param modules the module-loading context

   147

 * @param module_ptr return the new module via this, if not NULL

   148

 * @param info the info required to identify and load the module

   149

 * @param err return error info

   150

 */

   151

err_t module_load (struct modules *modules, struct module **module_ptr, const struct module_info *info, struct error_info *err);

   152

   153

/**

   154

 * Lookup a module by name

   155

 *

   156

 * @param modules the modules state

   157

 * @param name the module name to get

   158

 * @return the module struct, or NULL if not found

   159

 */

   160

struct module* module_get (struct modules *modules, const char *name);

   161

   162

/**

   163

 * Look up a module configuration option by name

   164

 */

   165

const struct config_option* module_conf_lookup (struct module *module, const char *name, struct error_info *err);

   166

   167

/**

   168

 * Apply a module configuration option using a structured value

   169

 */

   170

err_t module_conf (struct module *module, const struct config_option *opt, const struct config_value *value, struct error_info *err);

   171

   172

/**

   173

 * Set a module configuration option using a raw value

   174

 */

   175

err_t module_conf_raw (struct module *module, const char *name, char *value, struct error_info *err);

   176

   177

/**

   178

 * Unload a module. This means calling its 'unload' func, which will then go about shutting down the module. This might

   179

 * not happen right away, though, so the module is not destroyed yet.

   180

 *

   181

 * XXX: currently the module is never destroyed, there needs to be a "module unload done" callback...

   182

 */

   183

err_t module_unload (struct module *module);

   184

   185

/**

   186

 * Destroy a module, releasing as many resources as possible

   187

 */

   188

void module_destroy (struct module *module);

   189

   190

/**

   191

 * Unload all modules, this just calls module_unload for each module, logging errors as warnings.

   192

 *

   193

 * XXX: currently, this does not destroy any modules, or the modules state itself.

   194

 */

   195

err_t modules_unload (struct modules *modules);

   196

   197

/**

   198

 * Destroy all modules immediately.

   199

 *

   200

 * XXX: this doesn't leaves hanging module resources. The program will probably crash in soon

   201

 */

   202

void modules_destroy (struct modules *modules);

   203

   204

#endif