Updated Doc.

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required (VERSION 3.3.2)
 
-project(libmodule VERSION 4.0.0 LANGUAGES C CXX)
+project(libmodule VERSION 4.1.0 LANGUAGES C CXX)
 
 if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Release)

TODO.md

@@ -4,7 +4,7 @@
 - [x] Add an API to integrate module loop inside another loop
 - [x] modules_get_fd(const char *ctx)
 - [x] modules_dispatch(ctx)
-- [ ] Update Doc
+- [x] Update Doc
 - [ ] Add tests?
 
 ### Fixes

docs/conf.py

@@ -23,8 +23,8 @@
 copyright = '2019, Federico Di Pierro'
 author = 'Federico Di Pierro'
 
-version = '4.0.0'
-release = '4.0.0'
+version = '4.1.0'
+release = '4.1.0'
 
 highlight_language = "c"
 

docs/src/concepts.rst

@@ -37,3 +37,11 @@ This macro firstly creates a "myCtx" context, then a "test" module using same MO
 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(). 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 right after modules_get_fd(), 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|

docs/src/modules.rst

@@ -50,6 +50,20 @@ It abstracts all of libmodule internals mechanisms to provide an easy-to-use and
   :param quit_code: exit code that should be returned by modules_loop.
   :type quit_code: :c:type:`const uint8_t`
 
+.. c:macro:: modules_get_fd(fd)
+
+  Retrieve internal libmodule's events loop fd. Useful to integrate libmodule's loop inside client's own loop.
+
+  :param fd: pointer in which to store libmodule's fd
+  :type fd: :c:type:`int *`
+
+.. c:macro:: modules_dispatch(ret)
+
+  Dispatch libmodule's messages. Useful when libmodule's loop is integrated inside an external loop.
+
+  :param ret: ret >= 0 and MOD_OK returned -> number of dispatched messages. ret >= 0 and MOD_ERR returned -> loop has been quitted by a modules_quit() code, thus it returns quit_code. Ret < 0 and MOD_ERR returned: an error happened.
+  :type ret: :c:type:`int *`
+
 Multi-context API
 -----------------
 
@@ -90,3 +104,20 @@ It exposes very similar functions to single-context API (again, single-context i
   :type ctx_name: :c:type:`const char *`
   :type quit_code: :c:type:`const uint8_t`
 
+.. c:function:: modules_ctx_get_fd(ctx_name, fd)
+
+  Retrieve internal libmodule's events loop fd. Useful to integrate libmodule's loop inside client's own loop.
+
+  :param ctx_name: context name.
+  :param fd: pointer in which to store libmodule's fd
+  :type ctx_name: :c:type:`const char *`
+  :type fd: :c:type:`int *`
+
+.. c:function:: modules_ctx_dispatch(ctx_name, ret)
+
+  Dispatch libmodule's messages. Useful when libmodule's loop is integrated inside an external loop.
+
+  :param ctx_name: context name.
+  :param ret: ret >= 0 and MOD_OK returned -> number of dispatched messages. ret >= 0 and MOD_ERR returned -> loop has been quitted by a modules_quit() code, thus it returns quit_code. Ret < 0 and MOD_ERR returned: an error happened.
+  :type ctx_name: :c:type:`const char *`
+  :type ret: :c:type:`int *`