EDCMON.md

@@ -4,7 +4,6 @@ The Energy Data Center Monitor is a new EAR service for Data Center monitoring.
 
 EDCMON is 100% configurable and extensible since it uses an EAR framework named Plugin Manager which allows to load as many plugins as needed, which specific frequencies , dependencies among them and to share data between them. These plugins can communicate with each other through a **tag** (naming) system. The tag is a free text specified in the plugin code and is used as reference to specify dependencies, data sharing etc.
 
-
 ## The EDCMON executable
 
 EDCMON parameters are:
@@ -54,9 +53,10 @@ You can send N configuration messages to your plugin initialization function whi
 ./edcmon --plugins=metrics.so:2000+periodic_metrics.so:0000:config_message1:config_message2 --paths=path/to/plugins1:path/to/plugins2
 
 ./edcmon --plugins=metrics.so:2000+periodic_metrics.so:config_message1:config_message2 --paths=path/to/plugins1:path/to/plugins2
-
 ```
 
+**Caution!!** If the `config_message1` is a number, the Plugin Manager can understand that you are passing a time value instead an argument. You can set the calling time to 0 to avoid that misunderstanding.
+
 Plugins also have **dependencies**. It means that a plugin may depend on the actions or data shared by other plugins. A dependency is written in a string in the compiled binary itself, so you don't have to load it manually. It will be loaded automatically and its calling time could be the dependent plugin time (if specified in the binary). But if you want to set a specific calling time you have to load it manually and set the time you want. If a dependency is hard (which is specified in the string), a failure in the required plugin will disable the dependent plugin.
 
 Plugins also have **priorities**. If a plugin A is a dependency of plugin B, the plugin A will be called before. If a Plugin B was written before plugin A in the `--plugins` parameter, A will be called before, because these cases are contemplated in the dependency system algorithmics.
@@ -76,28 +76,43 @@ Even though in the plugins folder there are other plugins available (listed at t
 
 As previously said, the plugin periodic functions have to have concrete name. These functions names and arguments are the following:
 
-```
+```c
 void  up_get_tag         (cchar **tag, cchar **tags_deps)
 char *up_action_init     (cchar *tag, void **data_alloc, void *data)
 char *up_action_periodic (cchar *tag, void *data)
 char *up_post_data       (cchar *msg, void *data)
 ```
 
-The function `up_get_tag` is in charge of returning the plugin own tag and its dependency tags. A tag matches the name of the shared object file (without the extension). As seid, the dependency tags allows the Plugin Manager to search and open the tagged plugins automatically. The format is a tag list sepparated by plus signs. Example:
+The function `up_get_tag` is in charge of returning the plugin's own tag and its dependency plugins tags.
+A tag must match the name of the shared object file **without the extension**, i.e., a plugin named `my_plug.so` has the tag *my_plug*.
+Thus, dependency tags allows the Plugin Manager to search and open the tagged plugins automatically.
+The format is a tag list separated by plus *+* signs.
+For example:
 
-```
+```c
 void up_get_tag(cchar **tag, cchar **tags_deps)
 {
     *tag = "some_test";
     *tags_deps = "dependency1+!dependency2";
 }
 ```
-**If a dependency tag starts with some symbols** such as exclamation mark '!', it means that dependency is mandatory for the loading plugin, and in case it is not resolved the loading plugin will be disabled. The symbol '<' tells the Plugin Manager to inherit the timing of the dependant plugin.
+
+You can **prepend some symbols** to each dependency tag, which are used to set additional information about the dependency.
+This is the current set of dependency modifier symbols:
+
+| Symbol | Description |
+| ------ | ------ |
+| !    | The dependency is mandatory. |
+|  <      | Inherit the timing of the dependant plugin. |
+
+In the example above *dependency2* is set with the exclamation mark *"!"* prefixed, which means that the dependency is mandatory for the loading plugin, and in case it is not resolved the loading plugin will be disabled.
+
 
 The function `up_action_periodic()` or PA is the core function to perform actions and share data. It receives a tag and a pointer to the data associated with that tag. The received tag could be the self tag or the tag of other plugins. The plugin PA function will be called with its own tag and data when the specified time in `--plugins` argument has passed, or with other plugin tag and data after that plugin has called its own PA function with its own tag.
 
 Examples of PA function types:
-```
+
+```c
 char *up_action_periodic(cchar *tag, void *data)
 {
     if (is_tag("tag2")) {
@@ -115,7 +130,9 @@ char *up_action_periodic_tag1(cchar *tag, void *data)
 }
 ```
 
-As you can see, you can define a generic `up_action_periodic()` function or one with a suffixed tag. A suffixed function will be called only when a plugin whose tag matches the function tag suffix. If you define just a generic version of the function, take into the account that you have to distinguish between tags. The macro `is_tag` will help you to do this and maintain your code clean and verbose.
+As you can see, you can define a generic `up_action_periodic()` function or one with a suffixed tag.
+A suffixed function will be called only when a plugin's tag matches the function tag suffix.
+If you define just a generic version of the function, take into the account that you have to distinguish between tags. The macro `is_tag` will help you to do this and maintain your code clean and verbose.
 
 The returning char is a message that Plugin Manager will print in case is not NULL. You can add some modifiers at the beginning of the message:
 
@@ -123,9 +140,9 @@ The returning char is a message that Plugin Manager will print in case is not NU
 * `[=]` pauses the periodic call.
 * `[X]` closes the Plugin Manager main thread.
 
-The `up_action_init()` function works the same, it can receive the own plugin tag o other plugin tag. It is called one time before calling any PA function and can be used to allocate and initialize data.
+The `up_action_init()` function works the same, it can receive the own plugin tag o other plugin tag. It is called one time before calling any PA function and can be used to allocate and initialise data.
 
-```
+```c
 static mydata_t mydata;
 
 char *up_action_periodic_mytag (cchar *tag, void **data_alloc, void *data)
@@ -141,9 +158,9 @@ char *up_action_periodic_tag2 (cchar *tag, void **data_alloc, void *data)
 }
 ```
 
-When an initialization function is called and receives its own plugin tag, the `data_alloc` double pointer serves as pointer to the data that self plugin wants to share with other plugins, so it is responsible to allocate the data and set the address pointer. When an initialization function is called and receives other plugin tag, the `data_alloc` variable is NULL and `data` parameter points to the shared data newly initialized by their own plugin, which is the same data referenced in the PA function.
+When an initialisation function is called and receives its own plugin tag, the `data_alloc` double pointer serves as pointer to the data that self plugin wants to share with other plugins, so it is responsible to allocate the data and set the address pointer. When an initialisation function is called and receives other plugin tag, the `data_alloc` variable is NULL and `data` parameter points to the shared data newly initialised by their own plugin, which is the same data referenced in the PA function.
 
-The **configuration** string mentioned in EDCMON executable is also received when the initialization function is called with own plugin tag using the `data` parameter, and can be retrieved as a list of arguments:
+The **configuration** string mentioned in EDCMON executable is also received when the initialisation function is called with own plugin tag using the `data` parameter, and can be retrieved as a list of arguments:
 
 ```
 static mydata_t mydata;
@@ -183,7 +200,6 @@ PA example, if B and C depends on A in --plugins=A.so:4000+B.so:3000+C.so:4000
 12) And so on... 
 ```
 
-
 Finally, `up_post_data()` allows to receive external data to the plugins. In example, if Plugin Manager is being used by the EARD, when a job starts you could send a message to the framework containing the job and step IDs. By now you can distinguish the messages by `is_msg` macro. Maybe in the near future we implement the suffix system too.
 
 ### Helper macros