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 is a single function that is common to every context (thus does not need ctx_name param).

modules_set_memalloc_hook(hook)

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

Parameters:
  • hook (const memalloc_hook *) – 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_pre_start(void)

This function will be called by libmodule before creating any module. 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.

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.

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.

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.

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.