Added some docs.

TODO.md

@@ -4,25 +4,32 @@
 - [x] avoid strdupping topic when creating pubsub_msg_t
 - [x] Only use one pubsub msg for every module, instead of  creating one for each recipient
 - [x] Keep a reference count for each "sent" pubsub msg: when it reaches 0 it means all recipients received the message, and then in can be freed
-- [x] Add an autofree field to module_tell/module_pubsub that automatically frees sent data when last recipient receives it [DOCUMENT]
+- [x] Add an autofree field to module_tell/module_pubsub that automatically frees sent data when last recipient receives it
 - [x] Avoid strdupping module's name and ctx's name
-- [x] Avoid any allocation inside library and ALWAYS TRUST USER POINTER as core rule [DOCUMENT]
+- [x] Avoid any allocation inside library and ALWAYS TRUST USER POINTER as core rule
 - [x] Add a self() alias to _self
-- [x] module_subscribe/unsubscribe should return OK if already subscribed/not subscribed [DOCUMENT]
-- [x] Add new System messages: MODULE_STARTED/STOPPED [DOCUMENT]
-- [x] Avoid telling system messages like MODULE_STARTED/TOPIC_REGISTERED to ourselves [DOCUMENT]
+- [x] module_subscribe/unsubscribe should return OK if already subscribed/not subscribed
+- [x] Add new System messages: MODULE_STARTED/STOPPED
+- [x] Avoid telling system messages like MODULE_STARTED/TOPIC_REGISTERED to ourselves
 - [x] Test pubsub messagging for paused modules
 - [x] Fix memleaks!
 
 ### Generic
-- [x] Add some diagnostic API, eg: modules_dump() (to dump each module's state) [DOCUMENT]
-- [x] Add a module_load/unload function, to load a module from a compiled object at runtime [DOCUMENT]
+- [x] Add some diagnostic API, eg: module_dump() (to dump each module's state)
+- [x] Add a module_load/unload function, to load a module from a compiled object at runtime
 - [ ] simplify interface for module_load/unload? ie: module_load(path, ctx_name)
 - [x] Add test.so build to Easy example
 - [x] Re-evaluate module_register/deregister parameters (ie: self_t should not be a const!)
 
 ### Doc
-- [ ] Update API doc -> module_dump/load/unload(), new module_tell/publish(broadcast) parameter...
+- [x] module_dump
+- [x] module_subscribe/unsubscribe
+- [x] self()
+- [x] module_register/deregister
+- [ ] module_load/unload
+- [x] module_tell/publish/broadcast
+- [x] MODULE_STARTED/MODULE_STOPPED new sysmessages
+- [x] Avoid telling system messages like MODULE_STARTED/TOPIC_REGISTERED to ourselves
 - [ ] Add a new page about trusting pointers
 
 ### Samples

docs/src/module.rst

@@ -39,6 +39,12 @@ Where not specified, these functions return a :ref:`module_ret_code <module_ret_
   :type name: :c:type:`const char *` 
   :type ctxName: :c:type:`const char *` 
   :returns: void
+
+.. c:macro:: self()
+  
+  Returns _self variable for the module.
+
+  :returns: :c:type:`const self_t *`
 
 .. c:macro:: m_is(state)
 
@@ -66,10 +72,10 @@ Where not specified, these functions return a :ref:`module_ret_code <module_ret_
 
 .. c:macro:: m_become(new_recv)
 
-  Change receive callback to receive_new_recv
+  Change receive callback to receive_$(new_recv)
 
   :param new_recv: new module's receive callback; the function has prefix \receive_ concatenated with new_recv
-  :type new_recv: untyped
+  :type new_recv: :c:type:`const recv_cb`
 
 .. c:macro:: m_unbecome(void)
 
@@ -109,6 +115,10 @@ Where not specified, these functions return a :ref:`module_ret_code <module_ret_
   :type fmt: :c:type:`const char *` 
   :type args: :c:type:`variadic`
 
+.. c:macro:: m_dump()
+
+  Dump current module's state. Diagnostic API.
+
 .. c:macro:: 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.
@@ -134,48 +144,54 @@ Where not specified, these functions return a :ref:`module_ret_code <module_ret_
 
 .. c:macro:: m_subscribe(topic)
 
-  Subscribes the module to a topic.
+  Subscribes the module to a topic. If module is already subscribed to topic, MODULE_OK will be returned.
 
   :param topic: topic to which subscribe. Note that topic must be registered before.
   :type topic: :c:type:`const char *`
 
 .. c:macro:: m_unsubscribe(topic)
 
-  Unsubscribes the module from a topic.
+  Unsubscribes the module from a topic. If module is not subscribed to topic, MODULE_OK will be returned.
 
   :param topic: topic to which unsubscribe. Note that topic must be registered before.
   :type topic: :c:type:`const char *`
 
-.. c:macro:: m_tell(recipient, msg, size)
+.. c:macro:: m_tell(recipient, msg, size, autofree)
 
   Tell a message to another module.
 
   :param recipient: module to whom deliver the message.
   :param msg: actual data to be sent.
   :param size: size of data to be sent.
+  :param autofree: whether to autofree msg after last recipient's received it.
   :type recipient: :c:type:`const self_t *`
   :type msg: :c:type:`const unsigned char *`
   :type size: :c:type:`const ssize_t`
+  :type autofree: :c:type:`const bool`
 
-.. c:macro:: m_publish(topic, msg, size)
+.. c:macro:: m_publish(topic, msg, size, autofree)
 
   Publish a message on a topic.
 
   :param topic: topic on which publish message. Note that only topic creator can publish message on topic.
   :param msg: actual data to be published.
   :param size: size of data to be published.
+  :param autofree: whether to autofree msg after last recipient's received it.
   :type topic: :c:type:`const char *`
   :type msg: :c:type:`const unsigned char *`
   :type size: :c:type:`const ssize_t`
+  :type autofree: :c:type:`const bool`
 
-.. c:macro:: m_broadcast(msg, size)
+.. c:macro:: m_broadcast(msg, size, autofree)
 
   Broadcast a message in module's context.
 
   :param msg: data to be delivered to all modules in a context.
   :param size: size of data to be delivered.
+  :param autofree: whether to autofree msg after last recipient's received it.
   :type msg: :c:type:`const unsigned char *`
   :type size: :c:type:`const ssize_t`
+  :type autofree: :c:type:`const bool`
 
 .. c:macro:: m_tell_str(recipient, msg)
 
@@ -221,15 +237,15 @@ Again, where not specified, these functions return a :ref:`module_ret_code <modu
   :param hook: struct that holds this module's callbacks.
   :type name: :c:type:`const char *`
   :type ctx_name: :c:type:`const char *`
-  :type self: :c:type:`const self_t **`
+  :type self: :c:type:`self_t **`
   :type hook: :c:type:`const userhook *`
 
 .. c:function:: module_deregister(self)
 
   Deregister module
 
   :param self: pointer to module's handler. It is set to NULL after this call.
-  :type self: :c:type:`const self_t **`
+  :type self: :c:type:`self_t **`
 
 .. c:function:: module_is(self, state)
 
@@ -311,7 +327,7 @@ Again, where not specified, these functions return a :ref:`module_ret_code <modu
 
 .. c:function:: module_get_name(self, name)
 
-  Get module's name from his self pointer.
+  Get module's name from his self pointer
 
   :param self: pointer to module's handler
   :param name: pointer to storage for module's name. Note that this must be freed by user.
@@ -329,7 +345,7 @@ Again, where not specified, these functions return a :ref:`module_ret_code <modu
 
 .. c:function:: module_log(self, fmt, args)
 
-  Module's logger
+  Logger function for this module. Call it the same way you'd call printf
 
   :param self: pointer to module's handler
   :param fmt: log's format.
@@ -338,6 +354,13 @@ Again, where not specified, these functions return a :ref:`module_ret_code <modu
   :type fmt: :c:type:`const char *`
   :type args: :c:type:`variadic`
 
+.. c:function:: module_dump(self)
+
+  Dump current module's state. Diagnostic API.
+
+  :param self: pointer to module's handler
+  :type self: :c:type:`const self_t *`
+
 .. c:function:: 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.
@@ -369,7 +392,7 @@ Again, where not specified, these functions return a :ref:`module_ret_code <modu
 
 .. c:function:: module_subscribe(self, topic)
 
-  Subscribes the module to a topic.
+  Subscribes the module to a topic. If module is already subscribed to topic, MODULE_OK will be returned.
 
   :param self: pointer to module's handler
   :param topic: topic to which subscribe. Note that topic must be registered before.
@@ -378,46 +401,52 @@ Again, where not specified, these functions return a :ref:`module_ret_code <modu
 
 .. c:function:: module_unsubscribe(self, topic)
 
-  Unsubscribes the module from a topic.
+  Unsubscribes the module from a topic. If module is not subscribed to topic, MODULE_OK will be returned.
 
   :param self: pointer to module's handler
   :param topic: topic to which unsubscribe. Note that topic must be registered before.
   :type self: :c:type:`const self_t *`
   :type topic: :c:type:`const char *`
 
-.. c:function:: module_tell(self, recipient, msg, size)
+.. c:function:: module_tell(self, recipient, msg, size, autofree)
 
   Tell a message to another module.
 
   :param self: pointer to module's handler
   :param recipient: module to whom deliver the message.
   :param msg: actual data to be sent.
   :param size: size of data to be sent.
+  :param autofree: whether to autofree msg after last recipient's received it.
   :type self: :c:type:`const self_t *`
   :type recipient: :c:type:`const self_t *`
   :type msg: :c:type:`const unsigned char *`
   :type size: :c:type:`const ssize_t`
+  :type autofree: :c:type:`const bool`
 
-.. c:function:: module_publish(self, topic, msg, size)
+.. c:function:: module_publish(self, topic, msg, size, autofree)
 
   Publish a message on a topic.
 
   :param self: pointer to module's handler
   :param topic: topic on which publish message. Note that only topic creator can publish message on topic.
   :param msg: actual data to be published.
   :param size: size of data to be published.
+  :param autofree: whether to autofree msg after last recipient's received it.
   :type self: :c:type:`const self_t *`
   :type topic: :c:type:`const char *`
   :type msg: :c:type:`const unsigned char *`
   :type size: :c:type:`const ssize_t`
+  :type autofree: :c:type:`const bool`
 
-.. c:function:: module_broadcast(self, msg, size)
+.. c:function:: module_broadcast(self, msg, size, autofree)
 
   Broadcast a message to all modules inside context.
 
   :param self: pointer to module's handler
   :param msg: actual data to be published.
   :param size: size of data to be published.
+  :param autofree: whether to autofree msg after last recipient's received it.
   :type self: :c:type:`const self_t *`
   :type msg: :c:type:`const unsigned char *`
   :type size: :c:type:`const ssize_t`
+  :type autofree: :c:type:`const bool`

docs/src/pubsub.rst

@@ -26,9 +26,15 @@ Only module_is(), module_get_name/context() functions can be called passing as s
 System messages
 ---------------
 
-Beside USER messages (pubsub_msg_t.type), there are 4 system messages, with type respectively: LOOP_STARTED, LOOP_STOPPED, TOPIC_REGISTERED, TOPIC_DEREGISTERED. |br|
-These pubsub messages are automatically sent by libmodule (note that sender will be NULL) when matching functions are called. |br|
-For example, you can use TOPIC_REGISTERED message (note that pubsub_msg_t.topic will be valued matching newly created topic) to subscribe to a topic as soon as it appears in current context.
+Beside USER messages (pubsub_msg_t.type), there are 6 system messages, respectively: LOOP_STARTED, LOOP_STOPPED, TOPIC_REGISTERED, TOPIC_DEREGISTERED, MODULE_STARTED, MODULE_STOPPED. |br|
+These pubsub messages are automatically sent by libmodule when matching functions are called, eg: |br|
+* LOOP_STARTED(STOPPED) is sent whenever a loop starts(stops) looping. It is useful to actually start(stop) your pubsub messagging (eg: one module waits on LOOP_STARTED to send a pubsub message to another module, and so on...). It won't have any valued fields, except for type. |br|
+* TOPIC_(DE)REGISTERED message is sent when any module registers a topic; it is useful for other modules to (un)subscribe to it. |br|
+It will have valued type and topic fields; moreover, sender field will be set to module that (de)registered the topic. |br|
+* MODULE_STARTED(STOPPED) is sent whenever a module starts/resumes(stops/pauses). Again this is useful to inform other modules that a new module is available. |br|
+It will have valued type and sender fields; sender will be set to started(stopped) module.
+
+Finally, note that system messages with valued sender won't be sent to modules that actually generated the message.
 
 Notes
 -----