CalvinSys

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": {}
      }
    }
  }
}