Module API

Module API denotes libmodule interface functions to manage each module lifecycle.
It is splitted in two APIs.

Easy API

Module easy API consists of a single-context-multi-modules set of macros. It can be found in <module/module_easy.h>.
These macros make it easy and transparent to developer all of the module’s internal mechanisms, providing a very simple way to use libmodule.
It enforces correct modularity too: each module must have its own source file.
Where not specified, these functions return a module_ret_code.

MODULE(name)

Creates “name” module with a default context: declares all needed functions and creates both constructor and destructor that will automatically register/deregister this module at startup.
Finally, it declares a const self_t *_self global variable that will be automatically used in every function call.
Note that default context will be automatically created if this is the first module to bind on it.

Parameters:
  • name (const char *) – name of the module to be created
Returns:

void
MODULE_CTX(name, ctxName)

Creates “name” module in ctxName context: declares all needed functions and creates both constructor and destructor that will automatically register/deregister this module at startup.
Finally, it declares a const self_t *_self global variable that will be automatically used in every function call.
Note that ctxName context will be automatically created if this is the first module to bind on it.

Parameters:
  • name (const char *) – name of the module to be created
  • ctxName (const char *) – name of the context in which the module has to be created
Returns:

void
self()

Returns _self handler for the module.

Returns:const self_t *
m_load(path)

Attaches a new module from a .so file to “default” context. If module.so has a different context, this will be an error.

Parameters:
  • path (const char *) – shared object path.
m_unload(path)

Detaches a module loaded from a .so file.

Parameters:
  • path (const char *) – shared object path.
m_is(state)

Check current module’s state

Parameters:
  • state (const enum module_states) – state we are interested in; note that it can be an OR of states (eg: IDLE | RUNNING)
Returns:

false if module’ state is not ‘state’, true if it is and MOD_ERR on error.
m_start(void)

Start module’s polling

m_pause(void)

Pause module’s polling

m_resume(void)

Resume module’s polling

m_stop(void)

Stop module’s polling by closing its fds. Note that module is not destroyed: you can add new fds and call m_start on it. Moreover, its enqueued pubsub messages are destroyed.

m_become(new_recv)

Change receive callback to receive_$(new_recv)

Parameters:
  • new_recv (const recv_cb) – new module’s receive callback; the function has prefix receive_ concatenated with new_recv
m_unbecome(void)

Reset to default receive poll callback

m_set_userdata(userdata)

Set userdata for this module; userdata will be passed as parameter to receive callback

Parameters:
  • userdata (const void *) – module’s new userdata.
m_register_fd(fd, autoclose, userptr)

Registers a new fd to be polled by a module

Parameters:
  • fd (const int) – fd to be registered.
  • autoclose (const bool) – whether to automatically close the fd on module stop/fd deregistering.
  • userptr (const void *) – data to be passed in receive() callback msg->fd_msg_t when an event happens on this fd.
m_deregister_fd(fd)

Deregisters a fd from a module

Parameters:
  • fd (const int) – module’s old fd.
m_log(fmt, args)

Logger function for this module. Call it the same way you’d call printf.

Parameters:
  • fmt (const char *) – log’s format.
  • args (variadic) – variadic argument.
m_dump()

Dump current module’s state. Diagnostic API.

m_ref(name, modref)

Takes a reference from another module; it can be used in pubsub messaging to tell a message to it. It must not be freed.

Parameters:
  • name (const char *) – name of a module.
  • modref (const self_t **) – variable that holds reference to module
m_subscribe(topic)

Subscribes the module to a topic. If module is already subscribed to topic, MODULE_ERR will be returned. Note that a regex is a valid topic too.

Parameters:
  • topic (const char *) – topic to which subscribe.
m_unsubscribe(topic)

Unsubscribes the module from a topic. If module is not subscribed to topic, MODULE_ERR will be returned.

Parameters:
  • topic (const char *) – topic to which unsubscribe.
m_tell(recipient, msg, size, autofree)

Tell a message to another module.

Parameters:
  • recipient (const self_t *) – module to whom deliver the message.
  • msg (const void *) – actual data to be sent.
  • size (const ssize_t) – size of data to be sent.
  • autofree (const bool) – whether to autofree msg after last recipient’s received it.
m_publish(topic, msg, size, autofree)

Publish a message on a topic.

Parameters:
  • topic (const char *) – topic on which publish message. Note that only topic creator can publish message on topic.
  • msg (const void *) – actual data to be published.
  • size (const ssize_t) – size of data to be published.
  • autofree (const bool) – whether to autofree msg after last recipient’s received it.
m_broadcast(msg, size, autofree, global)

Broadcast a message.

Parameters:
  • msg (const void *) – data to be delivered to all modules in a context.
  • size (const ssize_t) – size of data to be delivered.
  • autofree (const bool) – whether to autofree msg after last recipient’s received it.
  • global (const bool) – whether to broadcast to every context.
m_tell_str(recipient, msg)

Tell a string message to another module. Size is automatically computed through strlen, and autofree is set to false.

Parameters:
  • recipient (const self_t *) – module to whom deliver the message.
  • msg (const char *) – message to be sent.
m_publish_str(topic, msg)

Publish a string message on a topic. Size is automatically computed through strlen, and autofree is set to false.

Parameters:
  • topic (const char *) – topic on which publish message. Note that only topic creator can publish message on topic.
  • msg (const char *) – message to be published.
m_broadcast_str(msg, global)

Broadcast a string message. Same as calling m_publish(NULL, msg). Size is automatically computed through strlen, and autofree is set to false.

Parameters:
  • msg (const char *) – message to be delivered to all modules in a context.
  • global (const bool) – whether to broadcast to every context.
m_poisonpill(recipient)

Enqueue a POISONPILL message to recipient. This allows to stop another module after it flushes its pubsub messages.

Parameters:
  • recipient (const self_t *) – RUNNING module to be stopped.

Complex API

Complex (probably better to say less-easy) API consists of `Module easy API`_ internally used functions. It can be found in <module/module.h> header.
Sometime you may avoid using easy API; eg: if you wish to use same source file for different modules, or if you wish to manually register a module.
Again, where not specified, these functions return a module_ret_code.

module_register(name, ctx_name, self, hook)

Register a new module

Parameters:
  • name (const char *) – module’s name.
  • ctx_name (const char *) – module’s context name. A new context will be created if it cannot be found.
  • self (self_t **) – handler for this module that will be created by this call.
  • hook (const userhook *) – struct that holds this module’s callbacks.
module_deregister(self)

Deregister module

Parameters:
  • self (self_t **) – pointer to module’s handler. It is set to NULL after this call.
module_load(path, ctx_name)

Attaches a new module from a .so file to ctx_name context. If module.so has a different context, this will be an error.

Parameters:
  • path (const char *) – shared object path.
  • ctx_name (const char *) – module’s context name.
module_unload(path)

Detaches a module loaded from a .so file.

Parameters:
  • path (const char *) – shared object path.
module_is(self, state)

Check current module’s state

Parameters:
  • self (const self_t *) – pointer to module’s handler.
  • state (const enum module_states) – state we are interested in; note that it can be an OR of states (eg: IDLE | RUNNING)
Returns:

false if module’state is not ‘state’, true if it is and MOD_ERR on error.
module_start(self)

Start module’s polling

Parameters:
  • self (const self_t *) – pointer to module’s handler
module_pause(self)

Pause module’s polling

Parameters:
  • self (const self_t *) – pointer to module’s handler
module_resume(self)

Resume module’s polling

Parameters:
  • self (const self_t *) – pointer to module’s handler
module_stop(self)

Stop module’s polling by closing its fds. Note that module is not destroyed: you can add new fds and call module_start on it. Moreover, its enqueued pubsub messages are destroyed.

Parameters:
  • self (const self_t *) – pointer to module’s handler
module_become(self, new_receive)

Change receive callback to new_receive

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • new_receive (const recv_cb) – new module’s receive.
module_set_userdata(self, userdata)

Set userdata for this module; userdata will be passed as parameter to receive callback.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • userdata (const void *) – module’s new userdata.
module_register_fd(self, fd, autoclose, userptr)

Register a new fd to be polled by a module

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • fd (const int) – fd to be registered.
  • autoclose (const bool) – whether to automatically close the fd on module stop/fd deregistering.
  • userptr (const void *) – data to be passed in receive() callback msg->fd_msg_t when an event happens on this fd.
module_deregister_fd(self, fd)

Deregister a fd from a module

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • fd (const int) – module’s old fd.
module_get_name(self, name)

Get module’s name from his self pointer

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • name (char **) – pointer to storage for module’s name. Note that this must be freed by user.
module_get_context(self, ctx)

Get module’s name from his self pointer.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • ctx (char **) – pointer to storage for module’s ctx. Note that this must be freed by user.
module_log(self, fmt, args)

Logger function for this module. Call it the same way you’d call printf

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • fmt (const char *) – log’s format.
  • args (variadic) – variadic argument.
module_dump(self)

Dump current module’s state. Diagnostic API.

Parameters:
  • self (const self_t *) – pointer to module’s handler
module_ref(self, name, modref)

Takes a reference from another module; it can be used in pubsub messaging to tell a message to it. It must not be freed.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • name (const char *) – name of a module.
  • modref (const self_t **) – variable that holds reference to module
module_subscribe(self, topic)

Subscribes the module to a topic. If module is already subscribed to topic, MODULE_ERR will be returned. Note that a regex is a valid topic too.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • topic (const char *) – topic to which subscribe.
module_unsubscribe(self, topic)

Unsubscribes the module from a topic. If module is not subscribed to topic, MODULE_ERR will be returned.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • topic (const char *) – topic to which unsubscribe.
module_tell(self, recipient, msg, size, autofree)

Tell a message to another module.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • recipient (const self_t *) – module to whom deliver the message.
  • msg (const void *) – actual data to be sent.
  • size (const ssize_t) – size of data to be sent.
  • autofree (const bool) – whether to autofree msg after last recipient’s received it.
module_publish(self, topic, msg, size, autofree)

Publish a message on a topic.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • topic (const char *) – topic on which publish message. Note that only topic creator can publish message on topic.
  • msg (const void *) – actual data to be published.
  • size (const ssize_t) – size of data to be published.
  • autofree (const bool) – whether to autofree msg after last recipient’s received it.
module_broadcast(self, msg, size, autofree, global)

Broadcast a message.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • msg (const void *) – data to be delivered to all modules in a context.
  • size (const ssize_t) – size of data to be delivered.
  • autofree (const bool) – whether to autofree msg after last recipient’s received it.
  • global (const bool) – whether to broadcast to every context.
module_poisonpill(self, recipient)

Enqueue a POISONPILL message to recipient. This allows to stop another module after it flushes its pubsub messages.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • recipient (const self_t *) – RUNNING module to be stopped.