Libmodule core/ctx API#
Ctx API denotes libmodule interface functions to manage contexts.
It can be found under <module/ctx.h>
.
NOTE: there is no context handler visible to user, because the handler is basically the thread itself. Trying to use the context API on a thread that has no context associated, will promptly return -EPIPE errno code.
Types#
typedef enum {
M_CTX_NAME_DUP = 1 << 0, // Should ctx's name be strdupped
M_CTX_NAME_AUTOFREE = 1 << 1, // Should ctx's name be autofreed
M_CTX_PERSIST = 1 << 2, // Prevent ctx automatic destroying when there are no modules in it anymore. With this option, context is kept alive until m_ctx_deregister() is called.
M_CTX_USERDATA_AUTOFREE = 1 << 3 // Automatically free ctx userdata upon deregister
} m_ctx_flags;
Bitmask of flags that can be passed to
m_ctx_register
function
typedef struct {
double activity_freq;
uint64_t total_idle_time;
uint64_t total_looping_time;
uint64_t recv_msgs;
size_t num_modules;
size_t running_modules;
} m_ctx_stats_t;
Returned stats about a context by
m_ctx_stats
function
typedef void (*m_log_cb)(const m_mod_t *ref, const char *fmt, va_list args);
Log callback set through
m_ctx_set_logger
function
Functions#
int m_ctx_register(const char *ctx_name, m_ctx_flags flags, const void *userdata);
Register a new ctx and associates it to current thread.
Params:
ctx_name
: name of the new ctxflags
: flags of the newly created ctxuserdata
: user pointer stored in the ctx
int m_ctx_deregister();
Deregister the ctx associated with the current thread.
NOTE: this API cannot be called if the ctx is still looping.
Make sure tom_ctx_quit
the loop before deregistering a context.
NOTE: unless a ctx is registered withM_CTX_PERSIST
flag, it will get
automatically destroyed when there are no more modules registered in it.
NOTE: all of the modules in the context will be deregistered
when their context gets deregistered.
int m_ctx_set_logger(m_log_cb logger);
Set a logger callback; otherwise, a default one is used.
Params:
logger
: new logger callback to be set
int m_ctx_loop(void);
Loop a ctx in a blocking manner, until
m_ctx_quit
is called by any module.
NOTE: stopping a ctx is a blocking action:
all present events will be flushed to their modules,
and, in case anyM_SRC_TYPE_TASK
src is enabled,
its thread will be joined for a clean exit.
Returns: m_ctx_quit
quit_code.
int m_ctx_quit(uint8_t quit_code);
Quit a ctx loop, returning given exit code.
Params:
quit_code
: quit value
int m_ctx_fd(void);
Retrieve ctx pollable file descriptor.
Returns: ctx fd.
int m_ctx_dispatch(void);
Dispatch events from the context.
Useful when ctx fd is embedded in another loop.
First time it gets called, it will start the loop;
then, consecutive calls will dispatch ctx events.
Finally, afterm_ctx_quit
has been called,
it will notify the ctx to stop.
NOTE: stopping a ctx is a blocking action: all present events will be flushed to their modules, and, in case anyM_SRC_TYPE_TASK
src is enabled, it will join its thread.
Returns: first time it is called: errno-style negative error code.
Subsequent calls: number of messages dispatched.
Last time (after a m_ctx_quit
call): errno-style negative error code.
int m_ctx_dump(void);
Dump a json of the current ctx state.
int m_ctx_stats(m_ctx_stats_t *stats);
Retrieve stats about current ctx state.
const char *m_ctx_name(void);
Retrieve ctx name.
const void *m_ctx_userdata(void);
Retrieve ctx userdata as set at registration time.
ssize_t m_ctx_len(void);
Retrieve number of registered modules.
int m_ctx_finalize(void);
Set the context as finalized, denying any subsequent module registeration.
int m_ctx_set_tick(uint64_t ns);
Set a context tick. You can subscribe modules to
M_PS_CTX_TICK
system topic to receive tick events.
Params:
ns
: nanoseconds for the tick
Only when built with WITH_FS
build option#
int m_ctx_fs_set_root(const char *path);
Set the context FS root. Must be set before the ctx loop is started.
Params:
path
: FS root path. NULL to disable FUSE fs.
int m_ctx_fs_set_ops(const struct fuse_operations *ops);
Set specified FUSE operations to context. Must be set before the ctx loop is started.
NOTE: module files will always be created readonly.
Params:
ops
: fuse operations. NULL to reset default ops.