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

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.

m_become(new_recv)

Change receive callback to receive_new_recv

Parameters:
  • new_recv (untyped) – 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_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_register_topic(topic)

Registers a new topic in module’s context.

Parameters:
  • topic (const char *) – topic to be registered. Only a not-existent topic can be registered. Note that as soon as a topic is registered, a message with type == SYSTEM will be broadcasted to all modules.
m_deregister_topic(topic)

Deregisters topic in module’s context.

Parameters:
  • topic (const char *) – topic to be deregistered. Only topic creator can deregister a topic.
m_subscribe(topic)

Subscribes the module to a topic.

Parameters:
  • topic (const char *) – topic to which subscribe. Note that topic must be registered before.
m_unsubscribe(topic)

Unsubscribes the module from a topic.

Parameters:
  • topic (const char *) – topic to which unsubscribe. Note that topic must be registered before.
m_tell(recipient, msg, size)

Tell a message to another module.

Parameters:
  • recipient (const self_t *) – module to whom deliver the message.
  • msg (const unsigned char *) – actual data to be sent.
  • size (const ssize_t) – size of data to be sent.
m_publish(topic, msg, size)

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 unsigned char *) – actual data to be published.
  • size (const ssize_t) – size of data to be published.
m_broadcast(msg, size)

Broadcast a message in module’s context.

Parameters:
  • msg (const unsigned char *) – data to be delivered to all modules in a context.
  • size (const ssize_t) – size of data to be delivered.
m_tell_str(recipient, msg)

Tell a string message to another module. Size is automatically computed through strlen.

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.

Parameters:
  • topic (const char *) – topic on which publish message. NULL to broadcast message to all modules in same context. Note that only topic creator can publish message on topic.
  • msg (const char *) – message to be published.
m_broadcast_str(msg)

Broadcast a string message in module’s context. Same as calling m_publish(NULL, msg). Size is automatically computed through strlen.

Parameters:
  • msg (const char *) – message to be delivered to all modules in a context.

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 (const 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 (const self_t **) – pointer to module’s handler. It is set to NULL after this call.
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.

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)

Module’s logger

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • fmt (const char *) – log’s format.
  • args (variadic) – variadic argument.
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_register_topic(self, topic)

Registers a new topic in module’s context.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • topic (const char *) – topic to be registered. Only a not-existent topic can be registered. Note that as soon as a topic is registered, a message with type == SYSTEM will be broadcasted to all modules.
module_deregister_topic(self, topic)

Deregisters topic in module’s context.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • topic (const char *) – topic to be deregistered. Only topic creator can deregister a topic.
module_subscribe(self, topic)

Subscribes the module to a topic.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • topic (const char *) – topic to which subscribe. Note that topic must be registered before.
module_unsubscribe(self, topic)

Unsubscribes the module from a topic.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • topic (const char *) – topic to which unsubscribe. Note that topic must be registered before.
module_tell(self, recipient, msg, size)

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 unsigned char *) – actual data to be sent.
  • size (const ssize_t) – size of data to be sent.
module_publish(self, topic, msg, size)

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 unsigned char *) – actual data to be published.
  • size (const ssize_t) – size of data to be published.
module_broadcast(self, msg, size)

Broadcast a message to all modules inside context.

Parameters:
  • self (const self_t *) – pointer to module’s handler
  • msg (const unsigned char *) – actual data to be published.
  • size (const ssize_t) – size of data to be published.