Backplane API Source

Backplane is the primary interface of Telem. Its job is to read all assigned InputAdapter objects, merge the returned MetricCollection values together, perform any necessary post-processing, and write the merged collection to all assigned OutputAdapter objects. This process is called a cycle, and there are methods available to run cycles on a schedule.

Properties

WARNING

All properties are set by Backplane and should not be mutated outside of this class.

Name	Type	Default
debugState 🔒	boolean	false
Internal debug state.
inputs 🔒	{ [string]: InputAdapter }	{}
Dictionary of assigned inputs.
outputs 🔒	{ [string]: OutputAdapter }	{}
Dictionary of assigned outputs.
middlewares 🔒	Middleware[]	{}
List of Middleware.
inputKeys 🔒	string[]	[]
List of InputAdapter names in processing order.
outputKeys 🔒	string[]	[]
List of OutputAdapter names in processing order.
collection 🔒	MetricCollection	MetricCollection()
Output collection from last cycle.
asyncCycleHandlers 🔒	fun()[]	{}
List of async cycle handlers.

Methods

Backplane

Backplane ()

Create a new Backplane.

addInput

Backplane:addInput (name: string, input: InputAdapter | fun()): self

Assigns an InputAdapter with the specified name to this Backplane. The input name will be used as an adapter label on each Metric during a cycle.

If input is a function, it will be converted into a Custom input first. See Custom Input for details on supported function signatures.

WARNING

It is recommended to have unique input names. While not strictly prohibited, behavior of cycle() with duplicate input names is undefined. This will be enforced in a future update.

addOutput

Backplane:addOutput (
  name: string,
  output: OutputAdapter | fun(collection: MetricCollection)
): self

Assigns an OutputAdapter with the specified name to this Backplane. If the adapter has set an async cycle handler, the handler will also be registered in this Backplane.

If output is a function, it will be converted into a Custom output first. See Custom Output for details.

addAsyncCycleHandler

Backplane:addAsyncCycleHandler (adapter: string, handler: fun())

Registers an async cycle handler for the specified adapter name.

cycle

Backplane:cycle (): self

At a high level, this function simply reads all the inputs and writes the collections to all the outputs. Below is a more detailed structure of this procedure:

• Initialize a temporary MetricCollection tempCollection
• Create an empty task queue inputTasks
• Loop over self.inputs in assignment order. For each InputAdapter, add a task to inputTasks:
  • Call input:read() in protected mode
  • If call fails, pass error to results
• Group tasks into chunks and execute in parallel
• Loop over task results in input assignment order:
  • If the input task failed, log an input fault to terminal and skip to next input
  • Process input middleware
  • For each Metric in the results, set metric.adapter to the name of the input. If metric.adapter is already set, prefix with the name of the input plus :.
• Set self.collection to tempCollection
• Cache output states
• Process backplane middleware
• Loop over self.outputs in assignment order. For each OutputAdapter:
  • Call output:write(tempCollection) in protected mode
  • If call fails, log an output fault to terminal and skip to next output
• Return self

cycleEvery

Backplane:cycleEvery (n: number): fun()

Returns a function that runs cycle(), sleeps for n seconds, and repeats. If any async cycle handlers have been registered, they will be individually returned from this function after the cycle scheduler, for example: return selfCycle, asyncHandler1, asyncHandler2.

updateLayouts

Backplane:updateLayouts (): self

Trigger eager layout updates on all attached outputs with updateLayout functions, such as Line Chart and other graphical adapters. Note that "eager" means the outputs will be re-rendered immediately after the layout is updated.

debug

Backplane:debug (state: boolean)

Set internal debug state. When state is true, Backplane will write verbose information to the terminal during a cycle. When state is false, Backplane will only write adapter faults to the terminal. Any adapters added after calling debug() will also have their debug state set to the same value.

cache

Backplane:cache (state: boolean)

Set output cache state. When state is true, Backplane will save the data history of cacheable output adapters to the filesystem at regular intervals. If the program or computer halts and restarts, the cache will be loaded and the output adapters will be re-initialized with the cached data. An output adapter must call self:cacheable(), as well as implement getState() and loadState(), to be cacheable.

middleware

Backplane:middleware (mw1: Middleware | fun(), mw2?: Middleware | fun(), ...): self

Set the middleware stack for this Backplane. Middleware will be executed in the order they are passed to this function. Middleware can be any class that inherits from Middleware.

If a function is passed, it will be converted into a Custom middleware first. See Custom Middleware for details on supported function signatures.

Usage

local telem = require 'telem'

local backplane = telem.backplane()

backplane:addInput('hello_in', telem.input.helloWorld(123))
backplane:addOutput('hello_out', telem.output.helloWorld())

-- run a single cycle (useful for custom scheduling)
backplane:cycle()

-- run a cycle every 5 seconds forever
parallel.waitForAll(
  backplane:cycleEvery(5),

  function ()
    while true do
      -- reactor.preventMeltdown()
      -- animals.feed()
      -- mission.accomplish()
      
      -- REMEMBER TO YIELD!
      sleep()
    end
  end
)