Dispatcher

From Bcontrol
Revision as of 22:46, 31 May 2007 by CarlosBrody (talk | contribs) (New page: __TOC__ == Overview of Dispatcher == Dispatcher is an interface between protocol code and the Real-Time Linux State Machine (RTLSM). It provides opening and closing of protocols, automati...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Overview of Dispatcher

Dispatcher is an interface between protocol code and the Real-Time Linux State Machine (RTLSM). It provides opening and closing of protocols, automatic segmentation of data from the RTLSM into trials, parsing of trials, and an automatic keeping track of trial and state machine history over trials. Dispatcher also takes care of the regular polling of the RTLSM.

Dispatcher is written using Solo, but to use the functionality that Dispatcher provides, you don't need to use or know Solo at all.


The action string and its 5 possible values

Dispatcher interacts with your protocol by calling your protocol code always with a single argument, a string usually called the "action." This can have one of 5 values:

'init'
This indicates initialization of the protocol: start any windows or GUIs that you may want to have, initialize variables, etc. Send the state machine definition for the first trial to dispatcher, to be forwarded to the RTLSM.
'close'
The protocol is to be closed. Delete your figure windows, delete your variables, etc.
'prepare_next_trial'
Dispatcher has detected that the RTLSM has entered one of the "prepare_next_trial" states. Your protocol should prepare the next trial's state machine definition, and send it to dispatcher to be forwarded to the RTLSM. You can send any state machine definition that you like. (But you should make sure that your state machine is guaranteed to hit "check_next_trial_ready" at some point, otherwise the next trial may never start!) At the same time, you should indicate which states in your definition form the "prepare_next_trial" states.
(Since the state machine definition can be different from trial to trial, so can the "prepare_next_trial" set.)
'trial_completed'
Dispatcher has detected a state_0 boundary, meaning that a trial has been completed and the next trial is about to start.
'update'
We are in the middle of a trial. Dispatcher has polled the RTLSM to ask for the latest events, and is reporting them to you.


Variables instantiated by Dispatcher

In addition to calling your protocol code with the above 5 different possible actions strings, Dispatcher will instantiate certain variables within your protocol, so that you have the content of these variables available to you. These variables will be regular Matlab variables (not SoloParamHandles). They will not be globals, but will be instantiated locally in your protocol's m-files. They are:

n_done_trials
The number of trials that have reached one of their "prepare_next_trial" states.
n_started_trials
The number of times the RTLSM has gone through state_0.
In between the initial state_0 in a trial, and entering the first of the "prepare_next_trial" states in that trial, n_started_trials=1+n_done_trials. In between entering the first of the "prepare_next_trial" states and the final state_0 in a trial, n_started_trials=n_done_trials.
n_completed_trials
This is always 1 less than n_started_trials. A trial is completed when the jump to state 0, to start the next trial, occurs.
parsed_events
A structure, the result of running disassemble.m with the 'parsed_structure' flag set to 1 on all the events that have occurred from the initial state_0 in the current trial until now.
parsed_events.states.state_0 is guaranteed to have at least one row, and that first row will be of the form [NaN t0] where t0 is the time of the start of the current trial. parsed_events.states.state_0 is guaranteed to have at most two rows. If the second row exists, the trial has been completed, and the second row is guaranteed to be of the form [t1 NaN] where t1 is the time of the end of the current trial.
parsed_events_history
A cell that is n_completed_trials-by-1 in size. Each element is the parsed_events structure for a completed trial. Thus, parsed_events_history{1} is the parsed_events structure for the 1st trial; parsed_events_history{4} is the parsed_events structure for the 4th trial; and so on.
latest_parsed_events
A structure, the result of running disassemble.m with the 'parsed_structure' flag set to 1 on all the events that have occurred from the last time the RTLSM was polled until now. If no events have occurred, all the elements of this structure will be empty. latest_parsed_events is a useful variable when you want to focus just on updating based on the most recent events.
current_assembler
A @StateMachineAssembler object, as was used for the current trial.
This is the object that is used to disassemble events into parsed_events and latest_parsed_events.
current_assembler_history
A cell that is n_completed_trials-by-1 in size. Each element is the current_assembler for a completed trial. Thus, current_assembler_history{1} is the current_assembler for the 1st trial; current_assembler_history{4} is the current_assembler for the 4th trial; and so on.
raw_events
A numeric matrix containing all the events from the start of the current trial until now, as obtained directly from the RTLSM.
parsed_events = disassemble(current_assembler, raw_events, 'parsed_structure', 1);
The first row of raw_events is guaranteed to be the transition out of state 0 that initiated the current trial. If the trial is completed, the last row of raw_events is guaranteed to be the transition into state 0.
raw_events_history
A cell that is n_completed_trials-by-1 in size. Each element is the raw_events for a completed trial. Thus, raw_events_history{1} is the raw_events for the 1st trial; raw_events_history{4} is the raw_events for the 4th trial; and so on.
parsed_events_history{n} = disassemble(current_events_history{n}, raw_events_history{n}, 'parsed_structure', 1);

Examples