Module library

Index:

module-delete module-init module-load module-monitor module-name module-notify module-save module-snapshots module-start module-stop remote-call

Functions:

module-delete

module-delete

Synopsis
Deletes a snapshot of the current module.
Usage
(module-delete snapshot_pattern)
Returns
result
Where
  • snapshot_pattern is string: a pattern to specify the snapshots to delete. That pattern may contain the symbol * as a wildcard.
  • result is string: a text indicating that the current module has been initialized.
Description
Deletes the snapshots of the current module whose name matches the specified pattern.
Examples
(module-delete "backup*")
"Snapshots deleted."
module-init

module-init

Synopsis
Initializes the current module.
Usage
(module-init)
Returns
result
Where
  • result is string
Description
Stops the current module and removes all data contained in global scope.
Examples
(module-init)
"Module sample initialized."
module-load

module-load

Synopsis
Loads a snapshot of the current module.
Usage
(module-load snapshot_name)
Returns
result
Where
  • snapshot_name is string[0..1]: the name of the snapshot to load. When omitted, the default snapshot ('head') is loaded.
  • result is string: a text indicating that the specified snapshot has been loaded.
Description
Loads the specified snapshot from persistent store into the memory of the current module. This operation do not stops the running executors and may cause unpredictible results. Stopping executors before loading a snapshot is always recommended.
Examples
(module-load)
"Module sample loaded."
(module-load "backup3")
"Module sample loaded."
Related functions
module-stop
module-monitor

module-monitor

Synopsis
Monitors a exterior function.
Usage
(module-monitor
  server_url
  module_name
  function_name
  listener
  "polling-interval" => polling_interval
  "access-key" => access_key
)
Returns
result
Where
  • server_url is string: The server url.
  • module_name is string: The module name.
  • function_name is string: The name of the exterior function to monitor.
  • listener is function: The listener function that will be called when the value returned by the exterior function changes. This listerer takes 3 parameters: (function_name value server_time).
  • polling_interval is number[0..1]: The polling interval in milliseconds.
  • access_key is string[0..1]: The access key that will be sent to the server.
  • result is string: "registered" when the listener is added, "unregistered" when it is removed, or null otherwise.
Description
When a listener is specified, this function monitors the specified exterior function from the given server and module. Whenever that exterior function returns a new value, the listener is called passing as arguments the name of the exterior function, the value it returned and the server time in milliseconds when this value was sent. Each listener runs in a different executor.
If the provided listener is null, the previous registered listener is removed.
See the REST API documentation for more information about monitoring exterior functions.
Examples
(module-monitor
  "http://localhost:9999"
  "test"
  "@temperature"
  (function (fn temp server_time)
    (set temperature temp)
  )
)
"registered"
(module-monitor
  "http://localhost:9999"
  "test"
  "@temperature"
  null
)
"unregistered"
Related functions
module-notify
module-name

module-name

Synopsis
Gets the name of the current module.
Usage
(module-name)
Returns
name
Where
  • name is string: the name of the current module.
Description
This function returns the name of the current module.
Examples
(module-name)
"energy_manager"
module-notify

module-notify

Synopsis
Notifies that the value returned by a exterior function has changed.
Usage
(module-notify function_name ... function_name)
Returns
listeners
Where
  • function_name is string[1..N]: the name of the exterior function that has changed.
  • listeners is number: the number of listeners that were monitoring the specified exterior functions.
Description
This function notifies all the listeners that were monitoring the value returned by the given exterior functions. These listeners are called in no special order.
A listener is registered with the module-monitor function.
Examples
(module-notify "@door_state")
3
(module-notify "@display" "@temperature")
0
Related functions
module-monitor
module-save

module-save

Synopsis
Saves a snapshot of the current module.
Usage
(module-save snapshot_name backup)
Returns
result
Where
  • snapshot_name is string[0..1]: the name of the snapshot that is going to be saved. When omitted, the default snapshot name ('head') is used.
  • backup is boolean[0..1]: when true, a copy of the specified snapshot is made before it is overwritten. The name of that copy is snapshot_name followed by the current date and time. By default, backup is false.
  • result is string: a text indicating that the module has been saved.
Description
Saves all data of the current module into persistent storage with the name snapshot_name. This function do not stops running executors and may produce an inconsistent snapshot image. Stopping executors before saving a module is always recommended.
Examples
(module-save)
"Module sample saved."
(module-save "backup3")
"Module sample saved."
Related functions
module-stop
module-snapshots

module-snapshots

Synopsis
List all snapshots of the current module.
Usage
(module-snapshots snapshot_pattern)
Returns
(snapshot ... snapshot)
Where
  • snapshot_pattern is string[0..1]: a pattern to filter the snapshots by name. That pattern may contain the symbol * as a wildcard.
  • snapshot is (
      "name" => name
      "last-modified" => last_modified
      "length" => length
    )    [0..N]: a module snapshot representation.
  • name is string: the name of the snapshot.
  • last_modified is number: the snapshot modification date/time expressed as the number of milliseconds elapsed since january 1st 1970 00:00h.
  • length is number: the size of the snapshot in bytes.
Description
Returns a list of the snapshots of the current module whose name matches the specified snapshot_pattern.
Examples
(module-snapshots "b*")
(
  (
    "name" => "backup1"
    "last-modified" => 1504118861000
    "length" => 4235
  )
  (
    "name" => "backup2"
    "last-modified" => 1504118876000
    "length" => 4604
  )
)
module-start

module-start

Synopsis
Starts the current module.
Usage
(module-start)
Returns
result
Where
  • result is string: a text indicating that the current module has been started.
Description
Starts the current module. When starting a module, the code contained in the start variable is executed. That code can initialize variables, listeners or hardware resources and also may spawn executors to perform repetivite tasks.
Examples
(module-start)
"Module facility started."
module-stop

module-stop

Synopsis
Stops the current module.
Usage
(module-stop)
Returns
result
Where
  • result is string: a text indicating that the current module has been stopped.
Description
Stops the current module. When stopping a module, the code contained in the stop variable is executed. That code may release resources and force the termination of the running executors. After the execution of stop, all remaining executors are killed.
Examples
(module-stop)
"Module facility stopped."
remote-call

remote-call

Synopsis
Calls an exterior function.
Usage
(remote-call function_setup arg ... arg)
Returns
result
Where
  • function_setup is list: A list containing the properties that describe the exterior function to call. These properties are url, request-headers, tenant, module and function. When function_setup contains the url property, an HTTP request is performed to call the function, otherwise the function is invoked locally, assuming that it is defined in the same server as the calling code. function_setup can also be a string representing the url of the exterior function to call. That url accepts 2 formats: protocol://host:port/path_to_function or module_alias:path_to_function where module_alias is a name defined in the setup/remote-modules list whose value points to the module url.
  • url is string[0..1]: The url of the exterior function.
  • request_headers is list[0..1]: The http request headers (name/value pairs).
  • tenant is string[0..1]: The tenant name of the exterior function. If omitted, the same tenant of the calling code is assumed.
  • module is string[0..1]: The module name of the exterior function. If omitted, the same module of the calling code is assumed.
  • function is string[0..1]: The path of the exterior function to call.
  • arg is list[0..N]: The argument to pass to the function. When more than one argument is specified, all them are added to a list that will be passed to the exterior function (function (ctx data) ...) as the data argument.
  • result is object: the value returned by the exterior function expressed in BPL format or null if the specified function is not an exterior function.
Description
Calls the exterior function specified in function_setup passing the given arguments evaluated locally. When the function is called through the HTTP protocol, the connect and read timeout are 10 and 30 seconds respectively. remote-call can only invoke exterior functions that return a response in BPL format.
Examples
(remote-call
  (
    "url" =>
    "https://localhost:9999/cars/@get-detections"
    "request-headers" => ("access-key" => "1234")
  )
)
(("car" 123) ("truck" 23))
(remote-call
  (
    "tenant" => "libs"
    "module" => "math"
    "function" => "fn/@distance-to"
    "request-headers" => ("access-key" => "1234")
  )
  x
  y
)
7.5456456
(do
  (set rc/distance-to
    (
      "module" => "math"
      "function" => "fn/@distance-to"
    )
  )
  (remote-call rc/distance-to x y)
)
7.5456456
(do
  (set math
    (function (fn)
      (list
        "module" => "math"
        "function" => (concat "@" fn)
      )
    )
  )
  (remote-call (math "sum") 1 2 3)
)
6
(remote-call
  "https://localhost:9999/libs/math/@distance-to"
  x
  y
)
7.5456456
(do
  (set setup/remote-modules/math
    "https://localhost:9999/libs/math"
  )
  (remote-call "math:@distance-to" x y)
)
7.5456456
Top