From 989eb533f1e529852525dc288a49dada4119a7de Mon Sep 17 00:00:00 2001
From: nirenjan <nirenjan@gmail.com>
Date: Thu, 2 Dec 2021 16:24:33 -0800
Subject: [PATCH] Add usage notes for module

---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1f7e26f..2009e2d 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,9 @@ build time by means of preprocessor flags.
 ## Logging macros
 
 Pinelog uses `printf` style formatting, using the following list of macros. The
-macro indicates the level at which the message is logged.
+macro indicates the level at which the message is logged. Note that Pinelog will
+automatically append a trailing newline to your log message, so you should not
+include one in your format string.
 
 * `PINELOG_FATAL`
 * `PINELOG_ERROR`
@@ -28,6 +30,40 @@ with an exit code of 1.
 PINELOG_INFO("configuration file %s not found, using defaults", config_file);
 ```
 
+## Modules
+
+Pinelog supports individual logging modules, which can be used by an application
+to individually control the log level for each module separately. This is
+managed at runtime, where the application must call `pinelog_init` to register a
+total count of modules, and then, for each module, it must call
+`pinelog_setup_module` to initialize the module name for that module. The module
+name is printed in the output.
+
+Pinelog also allows the log level of the module to default to the global log
+level. By default, module log level is set to `PINELOG_LVL_NOTSET`, which will
+force Pinelog to use the global log level for that module.
+
+In order to use the given module, the application must define `PINELOG_MODULE`
+before the line `#include "pinelog.h"`. If it is not defined, Pinelog will
+default to using the root module.
+
+### Example
+
+#### Initialization
+
+```C
+pinelog_init(2); // Initialize 2 modules
+pinelog_setup_module(0, "foo"); // Module 0 name is "foo"
+pinelog_setup_module(1, "bar"); // Module 1 name is "bar"
+```
+
+#### Inside module
+
+```C
+#define PINELOG_MODULE MODULE_FOO
+#include "pinelog.h"
+```
+
 ## Logging levels
 
 The default logging level is `ERROR`, and this can be controlled by the
@@ -44,6 +80,7 @@ definition, which is one of the following, in increasing order of priority.
 * `PINELOG_LVL_ERROR`
 * `PINELOG_LVL_FATAL`
 * `PINELOG_LVL_NONE`
+* `PINELOG_LVL_NOTSET` - for modules only
 
 Setting the level to a given priority suppresses all log messages of lower
 priority, i.e., if the level is set to `PINELOG_LVL_ERROR`, messages at
@@ -53,10 +90,14 @@ will be logged.
 **Note:** `PINELOG_LVL_NONE` suppresses all log messages, but `PINELOG_FATAL`
 will still terminate the program, even though nothing is logged.
 
+**Note:** `PINELOG_LVL_NOTSET` is only applicable to module log level, it will
+be rejected if the application attempts to use it for the global log level.
+
 ### Example
 
 ```C
 pinelog_set_level(PINELOG_LVL_WARNING);
+pinelog_set_module_level(MODULE_ID, PINELOG_LVL_TRACE);
 ```
 
 ```
@@ -86,7 +127,7 @@ pinelog_set_output_file("/var/log/app.log");
 Pinelog uses an opinionated logging format that is fixed as follows. Fields
 within `[]` are optional and controlled by build time flags.
 
-    [2021-07-14 11:08:04 ][ERROR: ][./test_pinelog.c:108 ]formatted message.
+    [2021-07-14 11:08:04 ][ERROR: ][./test_pinelog.c:108 ][module-name: ]formatted message.
 
 The program can be controlled by the following preprocessor flags, all of which
 default to `0` (disabled). Set the flag to `1` to enable it.
@@ -97,6 +138,8 @@ default to `0` (disabled). Set the flag to `1` to enable it.
 * `PINELOG_SHOW_BACKTRACE` - Display the file and line where the message is
   logged.
 
+Module name will always be displayed, if it is not the root module.
+
 Set these flags by using the `-D` compiler argument, .e.g.
 `-DPINELOG_SHOW_LEVEL=1 -DPINELOG_SHOW_DATE=1`
 
@@ -120,6 +163,28 @@ definitions.
 -DPINELOG_ERROR_STR=\"E\" -DPINELOG_FATAL_STR=\"F\"
 ```
 
+## Temporary buffer
+
+By default, Pinelog will write the individual components of the log output,
+i.e., date, log level, backtrace, module and log message individually to the
+output stream. The drawback of this is that if Pinelog is used in a
+multithreaded application, then the messages from multiple threads may be
+interleaved. In order to avoid this, you can define `PINELOG_BUFFER_SZ` to a
+positive value. This should be of sufficient size such that the largest log
+message can fit into this buffer, along with the individual components
+(timestamp, log level, etc.). A reasonable starting point for this is 256 bytes.
+
+Note that this will result in a greater use of stack space, so applications with
+limited stack space should not use this, or they risk a stack overflow.
+
+### Usage
+
+Add the following definition to your CFLAGS when building Pinelog
+
+```
+-DPINELOG_BUFFER_SZ=256
+```
+
 # Integrating Pinelog
 
 Pinelog is intended to be integrated into your application source tree, either