Modules API

Modules API denotes libmodule interface functions to manage context loop.
Like Module API, it has an easy, single-context API. Moreover, it has an equivalent multi-context API.
All these functions but modules_pre_start() return a module_ret_code.

Moreover, there are a bunch of functions that are common to every context (thus not needing ctx_name param).

modules_pre_start(void)

This function will be called by libmodule before doing anything else. It can be useful to set some global state/read config that are needed to decide whether to start a module. You only need to define this function and it will be automatically called by libmodule.

main(argc, argv)

Libmodule’s provide its own main implementation. This means that, on simplest cases, you’ll only have to write your modules and compile linking to libmodule. Libmodule’s main() is quite simple: it just runs modules_ctx_loop() on every registered context (in different pthreads for multiple contexts). Note that this is a weak symbol, thus it is obviously overridable by users.

Parameters:
  • argc (int) – number of cmdline arguments.
  • argv (char *[]) – cmdline arguments.
modules_set_memhook(hook)

Set memory management functions. By default: malloc, realloc, calloc and free are used.

Parameters:
  • hook (const memhook_t *) – new memory management hook.

Easy API

Modules easy API should be used in conjunction with Easy API.
It abstracts all of libmodule internals mechanisms to provide an easy-to-use and simple API. It can be found in <module/modules_easy.h> header.

modules_set_logger(logger)

Set a logger. By default, module’s log prints to stdout.

Parameters:
  • logger (const log_cb) – logger function.
modules_loop(void)

Start looping on events from modules. Note that as soon as modules_loop is called, a message with type == LOOP_STARTED will be broadcasted to all context’s modules. Moreover, loop is automatically stopped (with return code 0) if there are no more RUNNING modules in its context.

modules_quit(quit_code)

Leave libmodule’s events loop. Note that as soon as it is called, a message with type == LOOP_STOPPED will be broadcasted to all context’s modules.

Parameters:
  • quit_code (const uint8_t) – exit code that should be returned by modules_loop.
modules_get_fd(fd)

Retrieve internal libmodule’s events loop fd. Useful to integrate libmodule’s loop inside client’s own loop.

Parameters:
  • fd (int *) – pointer in which to store libmodule’s fd
modules_dispatch(ret)

Dispatch libmodule’s messages. Useful when libmodule’s loop is integrated inside an external loop. This is a non-blocking function (ie: if no data is available to be dispatched, it will return).

Parameters:
  • ret (int *) – ret >= 0 and MOD_OK returned -> number of dispatched messages. ret >= 0 and MOD_ERR returned -> loop has been quitted by a modules_quit() code, thus it returns quit_code. Ret < 0 and MOD_ERR returned: an error happened.

Multi-context API

Modules multi-context API let you manage your contexts in a very simple way. It is exposed by <module/modules.h> header.
It exposes very similar functions to single-context API (again, single-context is only a particular case of multi-context), that now take a “context_name” parameter.

modules_ctx_set_logger(ctx_name, logger)

Set a logger for a context. By default, module’s log prints to stdout.

Parameters:
  • ctx_name (const char *) – context name.
  • logger (const log_cb) – logger function.
modules_ctx_loop(ctx_name)

Start looping on events from modules. Note that this is just a macro that calls modules_ctx_loop_events with MODULE_MAX_EVENTS (64) events. Moreover, loop is automatically stopped (with return code 0) if there are no more RUNNING modules in its context.

Parameters:
  • ctx_name (const char *) – context name.
modules_ctx_loop_events(ctx_name, maxevents)

Start looping on events from modules, on at most maxevents events at the same time. Note that as soon as modules_loop is called, a message with type == LOOP_STARTED will be broadcasted to all context’s modules. Moreover, loop is automatically stopped (with return code 0) if there are no more RUNNING modules in its context.

Parameters:
  • ctx_name (const char *) – context name.
  • maxevents (const int) – max number of fds wakeup that will be managed at the same time.
modules_ctx_quit(ctx_name, quit_code)

Leave libmodule’s events loop. Note that as soon as it is called, a message with type == LOOP_STOPPED will be broadcasted to all context’s modules.

Parameters:
  • ctx_name (const char *) – context name.
  • quit_code (const uint8_t) – exit code that should be returned by modules_loop.
modules_ctx_get_fd(ctx_name, fd)

Retrieve internal libmodule’s events loop fd. Useful to integrate libmodule’s loop inside client’s own loop.

Parameters:
  • ctx_name (const char *) – context name.
  • fd (int *) – pointer in which to store libmodule’s fd
modules_ctx_dispatch(ctx_name, ret)

Dispatch libmodule’s messages. Useful when libmodule’s loop is integrated inside an external loop. This is a non-blocking function (ie: if no data is available to be dispatched, it will return).

Parameters:
  • ctx_name (const char *) – context name.
  • ret (int *) – ret >= 0 and MOD_OK returned -> number of dispatched messages. ret >= 0 and MOD_ERR returned -> loop has been quitted by a modules_quit() code, thus it returns quit_code. Ret < 0 and MOD_ERR returned: an error happened.