Global Set (gset)

Global set is a persistent set storage which can be used across templates. Unlike glob, gset can store multiple values.

Glob are great for storing persistent states, however saving multiple values inside them could be pain. Especially when multiple templates are using the same glob
structure, things can quickly turn messy because of Read/Modify/Write cycle. In order to avoid that, we have introduced another data type which can hold multiple
unique values.
gset can be used to store more than one unique value in a container. The elements stored in gset must be unique and can be deleted individually. gset provides a get function to list all the elements in the set.
Lets take an example

{
// implementing a Job distribution scenario here.
// Each worker is publishing its unique Id in global worker set
gset.add('workers', my_unique_id);
// Job distributers can get all available workers at any given time
var workers = gset.get('workers');
console.log(workers);
//Job assignement happens via other means. Once a worker is busy,
// it can remove itself from the global set
gset.delete('workers', my_unique_id);
// A global manager can also purge the entire set. All entries will be deleted.
gset.purge('workers');
}

gset are persistent across template lifetime and across simulations. They can be used to implement a variety of interaction between templates.
An example of this could be mailboxes. Each client can have its own mailbox and check for the messages to be arrived from others.
Another example is a work queue. Worker templates can post the job to a common work queues while consumer template can retrieve the jobs.

gset object provides following functions

gset.add(key, value, function(success){})

key: Must be a string

value: Could be a string, JSON, array or any other object.

callback: where success is true or false, indicating the result of operation.

The callback is called with true if the value can be added to specified set successfully, else false.
A set doesnt need to be created explicity. If set didn’t exist previously, it will be created.

Note: A duplicate value shall be overwritten as gset can only store unique value.

Note: If callback is ommitted, the API performs synchronously and returns the success bool. Synchronous calling slows down the simulation speed drastically and should be avoided.

gset.get(key, function(result){})

key: Must be a string

callback: will be called with result of the get operation. [] if key not found.

The callback will be called with an array of the value stored in gset object if found, else it returns an empty array.
The function try to JSON.parse() the return value so the objects are automatically converted, if possible.

If key can not be found, the function returns empty array []

Note: If callback is ommitted, the API performs synchronously and returns the success bool. Synchronous calling slows down the simulation speed drastically and should be avoided.

gset.delete(key, value, function(result){})

key: Must be a string

value: Could be a string, JSON, array or any other object.

callback: will be called with result of the delete operation. true if success, else false.

The API erases the value stored in gset object if found and return true else false. The value must exactly match the previously set value.

If value didn’t exists, it will return false.

Note: If callback is ommitted, the API performs synchronously and returns the result. Synchronous calling slows down the simulation speed drastically and should be avoided.

gset.purge(key, function(result){})

key: Must be a string

callback: will be called with result of the purge operation. true if success, else false.

The API removes the gset object completely from the memory. If gset object is found and deleted, it returns true else false.

Note: If callback is ommitted, the API performs synchronously and returns the success bool. Synchronous calling slows down the simulation speed drastically and should be avoided.