Overview

A BRAHMS Matlab Process is a Matlab function with structure closely analogous to the event() function of a native BRAHMS Process. The function has the form shown below, and is called by BRAHMS multiple times, with one or more calls being received for each of the framework Events sent by the Engine.

M Source Code (against 1258)
function [persist, output] = myprocess(persist, input)

Inputs and Outputs

The persist variable is initialised by BRAHMS before the first call is made, can be modified by the process during a call, or by BRAHMS between calls, but changes to it persist across calls. This means that the Process can use it to store its state, but means also that the Process should take care to keep the variable clean (particular cases described in the following) to minimise the overhead of passing it in and out of the function. Note that you should not use Matlab's own "persist" mechanism, since multiple instances of your process may get their data mixed up; the persist mechanism provided by BRAHMS is guaranteed by the framework to be safe in multi-processing environments.

The input variable is initialised anew on each call, and contains information that changes regularly (event data, time data, and input data, specifically).

The output variable is set by the process, and contains the process's response to BRAHMS, and optionally a list of operations (instructions) for BRAHMS to carry out. It can also be used to request that the current event "continue" - in this case, BRAHMS will perform the requested operations, and then call the process again with the same event, passing in any operation results. See Continuation.

Notes
  • You can view the state of any of these variables at any stage during processing simply by printing them using Matlab syntax, for example disp(input).

Function Body

The body of the process function, like that of the event() function in a native Process, is simply a switch statement on the event type, and a set of code sections that handle each different event (example below). The bindings propagate all relevant Process events to the Matlab function (actually, not everything quite is implemented, but we'll cover those cases in the following).

Example: Hello World

The example below is a functional BRAHMS Matlab Process. It takes no inputs, and generates no outputs, but executes just fine.

M Source Code (against 1258)
function [persist, output] = helloworld(persist, input) % default output (no response, no error, no operations) output = persist.output; % switch on event type switch input.event.type case persist.constants.EVENT_MODULE_INIT output.info.component = [0 1]; output.event.response = persist.constants.C_OK; case persist.constants.EVENT_STATE_SET output.event.response = persist.constants.C_OK; case persist.constants.EVENT_INIT_CONNECT disp('hello world!') output.event.response = persist.constants.C_OK; case persist.constants.EVENT_RUN_SERVICE disp(['mitch is still cool at t = ' int2str(input.time.now)]) output.event.response = persist.constants.C_OK; end