Merge pull request #221 from gtorodelvalle/task/fix-global-state-docu…

…mentation

Note about when 2 use global state variables to avoid Segmentation Fault

CHANGES_NEXT_RELEASE

@@ -1 +1,2 @@
 - [FEATURE] Maintaining global state between attribute-function-interpolator with distinct specifications
+- [TASK] Including a note about when to use global state variables to avoid Segmentation Fault

README.md

@@ -75,7 +75,7 @@ In case you would like to get information about the evolution of the fast-forwar
 
 Since the FIWARE Device Simulator CLI tool uses the [logops](https://www.npmjs.com/package/logops) package for logging, the logging level can be set using the `LOGOPS_LEVEL` environment variable. On the other hand, the logging format can be set using the `LOGOPS_FORMAT` environment variable.
 
-**NOTE:** There is an [issue](https://github.com/abbr/deasync/issues/55) in the `deasync` Node package which breaks fast-forward simulations which make use of the `attribute-function-interpolator` in MacOS machines. It works fine in Windows and Linux machines. So in case you are using a MacOS machine and need to use this functionality, we recommend creating a Docker image including the FIWARE Device Simulator and running the command from the container.
+**NOTE:** There is an [issue](https://github.com/abbr/deasync/issues/48) in the [`deasync`](https://www.npmjs.com/package/deasync) Node package which seems to break fast-forward simulations which make use of the `attribute-function-interpolator` in combination with entity attribute references (this is, `${{<entityId>}{<attributeName>}}` provoking a segmentation fault error. A workaround to avoid this issue is the use of global state variables updating the value of the attributes which need to be referenced and assigning their value to global state variables which make it possible to access them from any other `attribute-function-interpolator` instance.
 
 [Top](#top)
 
@@ -356,6 +356,7 @@ The simulation configuration file accepts the following JSON properties or entri
                 * A valid attribute value using the possibility to maintain global state between `attribute-function-interpolator` instances (no matter the Javascript code included in them): `"attribute-function-interpolator(module.exports = { result: ${{Entity:001}{active:001}} + globalVar1, state: { globals: { globalVar1: ++globalVar1 } }};)"`, where the result of the evaluation (this is, the value assigned to `module.exports.result`) will be the result of adding to the value of the `active:001` attribute of the `Entity:001` entity an increment equal to the value of the `globalVar1` global state variable, which will be incremented in 1 and passed as incremented to the next execution of an `attribute-function-interpolator` interpolator.
                 * It is important to note that global state variables (this is, amongst `attribute-function-interpolator` instances no matter their specification or associated Javascript code) and local state variables (this is, amongst `attribute-function-interpolator` instances with the same specification or associated Javascript code) can be combined following the guidelines detailed above. Notice that local state variables will impose over global state varaiables. This is, if a `attribute-function-interpolator` uses a local state variable with the same name as a global state variable, the local one will preserve and apply.
                 * A valid attribute value using the possibility to maintain local and global state amongst `attribute-function-interpolator` interpolator executions is: `"attribute-function-interpolator(/* state: counter = 1 */ module.exports = { result: ${{Entity:001}{active:001}} + counter + globalVar1, state: { counter: ++counter, globals: { globalVar1: ++globalVar1 } } };)"`, where the result of the evaluation (this is, the value assigned to `module.exports.result`) will be the result of adding to the value of the `active:001` attribute of the `Entity:001` entity an increment equal to the times the interpolator has been run plus the value of the `globalVar1` state variable (which, on the other hand, is incremented globally in 1 before exiting the evaluation of the Javascript code).
+                * **NOTE:** There is an [issue](https://github.com/abbr/deasync/issues/48) in the [`deasync`](https://www.npmjs.com/package/deasync) Node package which seems to break fast-forward simulations which make use of the `attribute-function-interpolator` in combination with entity attribute references (this is, `${{<entityId>}{<attributeName>}}` provoking a segmentation fault error. A workaround to avoid this issue is the use of global state variables updating the value of the attributes which need to be referenced and assigning their value to global state variables which make it possible to access them from any other `attribute-function-interpolator` instance.
         * **metadata**: Array of metadata information to be associated to the attribute on the update. Each metadata array entry is an object including 3 properties:
             * **name**: The metadata name.
             * **type**: The metadata type.