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 )
output = persist .output ;
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
|