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. Module initialization happens

    10

 * using a module_init_func_t named "<name>_init", which should return some kind of context pointer, which can later be

    11

 * used to perform other operations on the module.

    12

 */

    13

#include "nexus.h"

    14

#include "error.h"

    15

    16

#include <sys/queue.h>

    17

    18

/**

    19

 * Information required to load/identify a module.

    20

 */

    21

struct module_info {

    22

    /** Human-readable name */

    23

    const char *name;

    24

    25

    /** Filesystem path to the .so */

    26

    const char *path;

    27

};

    28

    29

/**

    30

 * A module's behaviour is defined as a set of function pointers, which is dynamically resolved from the module DSO,

    31

 * using the <mod_name>_funcs symbol.

    32

 */

    33

struct module_funcs {

    34

    /**

    35

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

    36

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

    37

     *

    38

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

    39

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

    40

     * @param err returned error info

    41

     */

    42

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

    43

    44

    /**

    45

     * Set a configuration option with the given name and value, given by the user. Configuration settings are not

    46

     * regarded as unique-per-name, but rather, several invocations of 'conf' with the same name and different values

    47

     * could set up a multitude of things.

    48

     *

    51

     *

    52

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

    53

     * @param name the name of the configuration setting

    54

     * @param value the value of the configuration setting

    55

     * @param err returned error info

    56

     */

    57

    err_t (*conf) (void *ctx, const char *name, char *value, struct error_info *err);

    58

};

    59

    60

/**

    61

 * A loaded module.

    62

 */

    63

struct module {

    64

    /** The identifying info for the module */

    65

    struct module_info info;

    66

    67

    /** The dlopen handle */

    68

    void *handle;

    69

    70

    /** The resolved function table */

    71

    struct module_funcs *funcs;

    72

    73

    /** The module context object */

    74

    void *ctx;

    75

    76

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

    77

    TAILQ_ENTRY(module) modules_list;

    78

};

    79

    80

/**

    81

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

    82

 */

    83

struct modules {

    84

    /** The nexus in use */

    85

    struct nexus *nexus;

    86

    87

    /** List of loaded modules */

    88

    TAILQ_HEAD(module_ctx_modules, module) list;

    89

};

    90

    91

/**

    92

 * Possible error codes

    93

 */

    94

enum module_error_code {

    95

    _ERR_MODULE_BEGIN = _ERR_MODULE,

    96

    97

    ERR_MODULE_OPEN,        ///< dlopen() failed

    98

    ERR_MODULE_NAME,        ///< invalid module_info.name

    99

    ERR_MODULE_SYM,         ///< invalid symbol

   100

    ERR_MODULE_INIT_FUNC,   ///< invalid module_init_func_t

   101

    ERR_MODULE_CONF,        ///< value error in configuration data

   102

};

   103

   104

   105

/**

   106

 * Maximum length of a module name

   107

 */

   108

#define MODULE_NAME_MAX 24

   109

   110

/**

   111

 * Maximum length of module symbol suffix

   112

 */

   113

#define MODULE_SUFFIX_MAX 16

   114

   115

/**

   116

 * Maximum length of symbol name name, including terminating NUL

   117

 */

   118

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

   119

   120

/**

   121

 * Create a new modules state

   122

 */

   123

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

   124

   125

/**

   126

 * Load a new module

   127

 *

   128

 * @param modules the module-loading context

   129

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

   130

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

   131

 * @param err return error info

   132

 */

   133

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

   134

   135

/**

   145

 * Set a module configuration option

   146

 */

   147

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

   148

   149

/**

   150

 * Unload a module

   151

 *

   152

 * XXX: not implemented

   153

 */

   154

err_t module_unload (struct module *module);

   155

   156

#endif