Initial work on new documentation.

Return -EPERM when m_map_put()ing to update a value in a map without M_MAP_ALLOW_UPDATE flag.

Author: FedeDP

.gitignore

@@ -64,3 +64,4 @@ docs/_build
 .idea/
 cmake-build-debug/
 cmake-build-release/
+venv/

Lib/priv.h

@@ -126,7 +126,7 @@ typedef struct {
     const void *userptr;
 } ev_src_t;
 
-/* Struct that holds pubsub messaging, private. It keeps reference count */
+/* Struct that holds pubsub messaging, private */
 typedef struct {
     m_evt_ps_t msg;
     m_ps_flags flags;

Lib/public/module/cmn.h.in

@@ -62,7 +62,7 @@ typedef enum {
     M_SRC_TYPE_PATH,  // Path Source
     M_SRC_TYPE_PID,   // PID Source
     M_SRC_TYPE_TASK,  // Task source -> M_SRC_ONESHOT flag is forced
-    M_SRC_TYPE_THRESH, // Threshold source -> M_SRC_ONESHOT flag is forced
+    M_SRC_TYPE_THRESH,// Threshold source -> M_SRC_ONESHOT flag is forced
     M_SRC_TYPE_END    // End of supported sources
 } m_src_types;
 

Lib/structs/map.c

@@ -178,25 +178,23 @@ static int hashmap_put(m_map_t *m, const char *key, void *value) {
         }
     }
 
-    bool insert = false;
-    if (!entry->key) {
+    if (entry->key) {
+        if (m->flags & M_MAP_VAL_ALLOW_UPDATE) {
+            if (m->dtor && entry->data != value) {
+                /* Destroy old value if needed */
+                m->dtor(entry->data);
+            }
+        } else {
+            /* No update allowed */
+            return -EPERM;
+        }
+    }  else {
         entry->key = key;
         m->length++;
-        insert = true;
-    } 
-    
-    if (m->flags & M_MAP_VAL_ALLOW_UPDATE) {
-        if (m->dtor && entry->data != value) {
-            /* Destroy old value if needed */
-            m->dtor(entry->data);
-        }
-        insert = true;
-    }
-    
-    if (insert) {
-        entry->data = value;
-        m->last_insert = entry;
     }
+
+    entry->data = value;
+    m->last_insert = entry;
     return 0;
 }
 

docs/index.rst

@@ -11,10 +11,9 @@ Welcome to libmodule's documentation!
    :caption: Contents:
 
    src/concepts
-   src/data_structures
    src/callbacks
    src/lifecycle
-   src/memory
+   src/easy
    src/pubsub
    src/module
    src/modules

docs/src/callbacks.rst

@@ -3,55 +3,59 @@
    <br />
 
 Callbacks
-================
+=========
 
-Every module needs 5 functions that must be defined by developer. |br|
-If using :ref:`module_easy`, they are automatically declared by MODULE macro. |br|
-Moreover, a module_pre_start function is declared too, but it is not needed by libmodule interface, ie: it can be left undefined. Your compiler may warn you about that though. |br|
-When using :ref:`module_complex` API, libmodule only mandates init() and receive() callbacks. A NULL check() and evaluate() functions mean to avoid checking and evaluating and thus starting module right away.
+Every module requires following functions to be defined by developers. |br|
+If using :ref:`easy` API, they are automatically declared by M_MOD() macro. |br|
+Moreover, a m_mod_pre_start function is declared too, but it is not needed by libmodule interface, ie: it can be left undefined. Your compiler may warn you about that though. |br|
+Note that libmodule only mandates m_evt_cb() callback. |br|
+Leaving other callbacks as NULL means starting module right away with no further checks. |br|
 
 .. code::
 
-    static void module_pre_start(void);
-    static bool init(void);
-    static bool check(void);
-    static bool evaluate(void);
-    static void receive(const msg_t *const msg, const void *userdata);
-    static void destroy(void);
+    void m_mod_pre_start(void);
+    bool m_start_cb(m_mod_t *mod);
+    bool m_eval_cb(m_mod_t *mod);
+    void m_evt_cb(m_mod_t *mod, const m_evt_t *const evt);
+    void m_stop_cb(m_mod_t *mod);
 
-.. c:function:: module_pre_start(void)
+.. c:function:: m_mod_pre_start(void)
 
   This function will be called before any module is registered. |br|
-  It is the per-module version of :ref:`modules_pre_start <modules_pre_start>` function.
+  It is the per-module version of :ref:`m_ctx_pre_start <m_ctx_pre_start>` function.
 
-.. c:function:: init(void)
+.. c:function:: m_start_cb(mod)
 
-  Initializes module state; useful to register any fd to be polled or to register any topic. |br|
-  Note that init() is called each time module is started. |br|
-  If init callback returns false, module is automatically stopped as its initialization failed.
+  Initializes module state; useful to register any event source. |br|
+  It is called whenever module is started. |br|
+  If m_mod_on_start callback returns false, module is automatically stopped as its initialization failed.
 
-.. c:function:: check(void)
+  :param: :c:type:`m_mod_t *` mod: pointer to module.
 
-  Startup filter to check whether this module should be actually created and managed by libmodule. |br|
-  
-  :returns: true if the module should be registered, false otherwise.
+  :returns: true if the module should be started, false otherwise.
 
-.. c:function:: evaluate(void)
+.. c:function:: m_eval_cb(mod)
 
-  Similar to check() function but at runtime: this function is called for each IDLE module after evey state machine update
-  and it should check whether a module is now ready to be start (ie: init should be called on this module and its state should be set to RUNNING). |br|
-  Use this to check intra-modules dependencies or any other env variable.
-  
-  :returns: true if module is now ready to be started, else false.
-  
-.. c:function:: receive(msg, userdata)
+  This function is called for each IDLE module after evey state machine update, |br|
+  and it should check whether a module is now ready to be started. |br|
+
+  :param: :c:type:`m_mod_t *` mod: pointer to module.
 
-  Poll callback, called when any event is ready on module's fd or when a PubSub message is received by a module. |br|
-  Use msg->is_pubsub to decide which internal message should be read (ie: ps_msg_t or fd_msg_t).
+  :returns: true if module is now ready to be started, false otherwise.
 
-  :param: :c:type:`const msg_t * const` msg: pointer to msg_t struct.
-  :param: :c:type:`const void *` userdata: pointer to userdata as set by m_set_userdata.
+.. c:function:: m_evt_cb(mod, evt)
+
+  Poll callback, called when any event is ready to be received by a module. |br|
+  Use evt->type to establish which event source triggered the event. |br|
+  Note that evt is memory-ref'd. Thus, if you want to keep a message alive, you need to m_mem_ref() it. |br|
+  Remember to unref it when done or you will cause a leak. |br|
+
+  :param: :c:type:`m_mod_t *` mod: pointer to module.
+  :param: :c:type:`const m_evt_t * const` evt: pointer to event.
+
+.. c:function:: m_stop_cb(mod)
 
-.. c:function:: destroy(void)
+  Called whenever module gets stopped, either by deregistration or m_mod_stop(). |br|
+  Useful to cleanup module state, eg: freeing some data or closing fds registered without M_SRC_FD_AUTOCLOSE flag. |br|
 
-  Destroys module, called automatically at module deregistration. Please note that module's fds set as autoclose will be closed.
+  :param: :c:type:`m_mod_t *` mod: pointer to module.

docs/src/concepts.rst

@@ -8,41 +8,28 @@ Concepts
 Module
 ------
 
-A module is core entity of libmodule: it is a single and indipendent logical unit that reacts to certain events, both pubsub and socket ones. |br|
-It can be seen as an Actor with the power of managing socket events. |br|
-It offers some callbacks that are used by libmodule to manage its life. |br|
-It is initialized through MODULE macro:
-   
-.. code::
-    
-    MODULE("test")
-    
-This macro creates a "test" module. |br|
-MODULE macro also creates a constructor and destructor that are automatically called by libmodule at start and at end of program. |br|
-Finally, this macro declares all of needed callbacks and returns an opaque handler for the module, that will be transparently passed with each call to libmodule API while using :ref:`module_easy`. |br|
+A module is core entity of libmodule: it is a single and indipendent logical unit that reacts to events. |br|
+It can be seen as an Actor with the ability of managing non-PubSub events. |br|
+It requires some callbacks that are used by libmodule to manage its life. |br|
 
 Context
 -------
 
-A context is a way to create subnets of modules. You can loop on events from each context, and each context behaves independently from others. |br| 
+A context can be seen as a collector for modules. You can loop on events from each context, and each context behaves independently from others. |br|
 This can be particularly useful when dealing with 2+ threads; ideally, each thread has its own module's context and thus its own events to be polled. |br|
-A context is automatically created for you first time a module that binds on that context is registered; so, multi-context API is very similar to single context one. |br|
-To initialize a module binding it to its context, use MODULE_CTX macro:
-   
-.. code::
-    
-    MODULE_CTX("test", "myCtx")
-    
-This macro firstly creates a "myCtx" context, then a "test" module using same MODULE macro as before. |br|
-Indeed, MODULE macro is only a particular case of MODULE_CTX macro, where myCtx is automatically setted to "default". |br|
-This makes sense, as you can expect: single context API is a multi context API with only 1 context. |br|
 Modules can only see and reach (through PubSub messaging) other modules from same context. |br|
 
 Loop
 ----
 
-Libmodule offers an internal loop, started with modules_ctx_loop(); note that each context has its own loop. |br|
-Moreover, you can even easily integrate it into your own loop: modules_ctx_get_fd() will retrieve a pollable fd and POLLIN events will be raised whenever a new message is available. |br|
-Remember that before starting your loop, modules_ctx_dispatch() should be called, to dispatch initial "LoopStarted" messages to each module. |br|
-Then, whenever POLLIN data is available on libmodule's fd, you only need to call modules_ctx_dispatch() again. |br|
-Finally, remember to close() libmodule's fd retrieved through modules_ctx_get_fd(). |br|
+Libmodule offers an internal loop, started with m_ctx_loop(); note that each context has its own loop. |br|
+Moreover, you can even easily integrate it into your own loop: m_ctx_get_fd() will retrieve a pollable fd and POLLIN events will be raised whenever a new message is available. |br|
+Remember that before starting your loop, m_ctx_dispatch() should be called, to dispatch initial "LoopStarted" messages to each module. |br|
+Then, whenever POLLIN data is available on libmodule's fd, you only need to call m_ctx_dispatch() again. |br|
+Finally, remember to close() libmodule's fd retrieved through m_ctx_get_fd(). |br|
+
+Source
+------
+
+Each module's listens to events by registering sources. |br|
+A source can be a timer, a topic (for PubSub communications between modules), a signal, a socket, etc etc. |br|

docs/src/data_structures.rst

@@ -0,0 +1,50 @@
+.. |br| raw:: html
+
+   <br />
+
+Easy API
+========
+
+MOD macro
+=========
+
+Libmodule easy API allows simple single-context applications developing. |br|
+It offers a
+
+.. code::
+
+    M_MOD(name)
+
+macro that automatically manages a module's lifecycle for you. |br|
+Moreover, it declares all needed callbacks as seen in :ref:`callbacks`. |br|
+Finally, a m_mod_pre_start function is declared too, but it is not needed by libmodule interface, ie: it can be left undefined. Your compiler may warn you about that though. |br|
+
+.. code::
+
+    static void m_mod_pre_start(void);
+    static bool m_mod_on_start(m_mod_t *mod);
+    static bool m_mod_on_eval(m_mod_t *mod);
+    static void m_mod_on_evt(m_mod_t *mod, const m_evt_t *const msg);
+    static void m_mod_on_stop(m_mod_t *mod);
+
+.. c:function:: m_mod_pre_start(void)
+
+  This function will be called before any module is registered. |br|
+  It is the per-module version of :ref:`m_ctx_pre_start <m_ctx_pre_start>` function.
+
+Provided Main
+=============
+
+Libmodule offers a weak, thus overridable, default main symbol that just loops on default ctx. |br|
+To further customize it, a weak m_ctx_pre_loop() function is also available, called by default main. |br|
+You can use this function to eg: parse argv parameters or read some config values. |br|
+
+.. c:function:: m_ctx_pre_loop(c, argc, argv)
+
+  Called by default main. |br|
+  Useful to initialize your program before libmodule starts looping on default context. |br|
+
+  :param: :c:type:`m_ctx_t *` c: pointer to context.
+  :param: :c:type:`int` argc: number of commandline arguments.
+  :param: :c:type:`char *[]` argv: array of commandline arguments strings.
+