Skip to content
This repository has been archived by the owner on Aug 13, 2020. It is now read-only.

CalvinSys

fswensson edited this page Nov 22, 2017 · 1 revision

CalvinSys

CalvinSys abstracts and defines a unified interface for actors to access platform functionality.

Actors interfacing CalvinSys objects

Actors interface CalvinSys by importing the calvinsys class from the calvin.actor.actor module and by using its static methods:

  • open(actor, name, **kwargs) - Calls the init() function of the object registered with name and returns a reference to be used in subsequent calls on the object. Enclosed key value arguments (kwargs) are merged with the attributes from the config with precedence of config attributes.
  • can_write(ref) - Query if data can be written.
  • write(ref, data) - Write data.
  • can_read(ref) - Query if data can be read.
  • read(ref) - Read data.
  • close(ref) - Objects are automatically closed when an actor is destroyed, use close to manually close the object if needed.

Example:

from calvin.actor.actor import Actor, manage, stateguard, calvinsys
...
  @manage(['period', 'timer'])
  def init(self, period):
    self.period = period
    self.timer = calvinsys.open(self, "sys.timer.repeating", period=5)

  @stateguard(lambda self: calvinsys.can_read(self.timer))
  def triggered(self):
    # Do something
    calvinsys.read(self.timer) # Ack timer
...

Adding new CalvinSys objects

Implementations of CalvinSys objects should be placed as subfolders to calvin/runtime/south/calvinsys/ and inherit from the BaseCalvinsysObject class and override:

  • init(self, **kwargs) - Initialize the object, kwargs contains the arguments from init() and the attributes from the configuration.
  • can_write(self) - Return if data can be written.
  • write(self, data) - Write data.
  • can_read(self) - Return if data can be read.
  • read(self) - Return data.
  • close(self) - Close the object.
  • serialize(self) - Return object state in JSON format to be included when serializing the actor, the object reference should be part of the managed list (@manage decorator).
  • deserialize(self, state, **kwargs) - Initialize object from previous serialized state, the object reference should be part of the managed list (@manage decorator).

All functions except close(), serialize() and deserialize() requires a JSON schema defined with:

  • init_schema = {}
  • can_write_schema = {}
  • write_schema = {}
  • can_read_schema = {}
  • read_schema = {}

Used both to validate the in- and out-data and as documentation. Example:

can_read_schema = {
    "description": "Returns True if timer has triggered, otherwise False",
    "type": "boolean"
}

Configuring CalvinSys object

CalvinSys objects are configured and added to a runtime as capabilities in Calvin's config by defining a name for the capability, the module that implements the interface and attributes to pass when calling init(). Example:

{
  "calvinsys": {
    "capabilities": {
      "sys.timer.repeating": {
          "module": "sys.timer.Timer",
          "attributes": {"repeats": true}
      },
      "sys.timer.once": {
          "module": "sys.timer.Timer",
          "attributes": {}
      }
    }
  }
}
Clone this wiki locally