View source for BrainStreamParallelMode

<!---Start1--->
= Parallel Mode =
__TOC__

BrainStream supports designs with multiple Matlab sessions running in parallel, where each Matlab session is responsible for executing different actions. For example, you may want to dedicate one Matlab session to stimulus presentation, whereas another Matlab session executes all data processing actions. In a design with only one Matlab session all actions are performed serially, but a design with multiple Matlab sessions enables parallel processing, which can speed up your experiment considerably. All Matlab sessions apart from the one running BrainStream are called ''clients''. In the following, we will describe the steps that are needed to direct the execution of actions to one or more clients.

<div id="SecClients"></div>
== Clients ==

All Matlab sessions apart from the one running BrainStream are called ''clients''. A client can either run on the same machine as the BrainStream Matlab session (i.e. an ''internal client'') or on another machine (i.e. an ''external client''). A client's name can be the IP or DNS address of the computer on which it runs, however, to prevent confusion, it is advised to use aliases. For example, you could call the stimulus presentation client 'stim'. In the block files of your experiment, you can define the actual address of the client (see [[BrainStreamParallelMode#BlockFiles|Modifications to the block files]]).

<div id="BlockFiles"></div>
== Modifications to the block files ==

Some extra settings need to be defined in the [[BrainStreamBuildingExperiments#SecBlock|block files]].

The first step is to tell BrainStream that parallel execution of actions is required. You can do this by setting topic RunMode and key Parallel to 1:

<tt>[RunMode]<br /> Parallel = 1</tt>

Second, you can define the actual address of the client under topic Clients. There are several ways to do this, depending on whether you are using an external or internal client.

External clients:<br /> <tt>[Clients]<br /> myclient = '123.456.0.1' % specify the IP or DNS address of the client machine</tt>

Internal clients:<br /> <tt>[Clients]<br />myclient = 'cores' % BrainStream chooses any available parallel core<br />myclient = 'core#' % BrainStream always takes core# (# is a number) and queues jobs if core is busy<br />myclient = 'localhost' % 'localhost' is an alias for your own computer's dns address<br />myclient = 'local' % BrainStream executes actions serial-wise (no parallel execution)</tt>

<div id="ActionsTable"></div>

== Modifications to the Actions table ==

In your [[BrainStreamBuildingExperiments#SecActions|Actions table]], fill in the name of your client in the client column. All actions specified in the corresponding row of the table will be executed at this client. For example:
{| class="wikitable"
|-
| '''<strong>marker <br /></strong>''' || '''<strong>time <br /></strong>''' || '''<strong>function <br /></strong>''' || '''<strong>client <br /></strong>''' || '''<strong>myfig<br /></strong>''' || '''myvar''' 
|-
| BS_INIT || EVENT || bs_insert_marker('show_fig',0) || || || [] 
|-
| show_fig || EVENT || show_figure(myfig) || stim || get || 
|-
| || DATA || fnc1 || || || get, put 

|}

This example table specifies the action of displaying a figure on the screen. The presentation of this figure is taken care of by the client called 'stim'. At the BS_INIT marker, the Matlab session running BrainStream inserts the marker 'show_fig'. When this marker arrives, the stim client retrieves the content of [[BrainStreamImportantConcepts#SecVariables|global variable]] 'myfig' and displays the figure. At the moment selected data for that event becomes available (time=DATA), the BrainStream Matlab session executes function fnc1 and updates changes made to the <tt>myvar</tt> variable.

BrainStream does not put restrictions on the type of returned global variables created during executed functions at the client. However, users should for instance realize that created figures only exist at that specific client and a global variable with corresponding figure handle is just returning a number to BrainStreams user state. This will work flawlessly as long as the table definitions keep sending corresponding events to the same client that holds the figure. Similar, if a type object global variable is returned to BrainStream, it will call its destructor and when sent to the client again it will be exactly reconstructed again. Besides the risk of some unintended processing overhead, a bigger risk lies in the destructor. In case content is destroyed that is defined beyond the scope of the object, it will be definitely lost and make your experiment crash. An example would be an object property that defines a handle to a figure and the destructor deletes this figure. Although the object would be reconstructed perfectly, the figure is not and any attempts to access the figure will result in an error. Whenever you decide to use these type of variables, keep this behavior in mind.

Multiple Matlab sessions cannot simultaneously modify the same global variable. For more information, see [[BrainStreamParallelMode#LockingMechanism|Locking mechanism for global variables]].

== Starting clients ==
For external clients, you need to start a new Matlab session and connect it to BrainStream. You can do this by means of the following function:<br />
<tt>
connect_brainstream_client('ip_address') % specify the ip-address of the computer running BrainStream
</tt>

Internal clients are started automatically, except when you are using the 'localhost' option. In that case, you must start a second Matlab session on the machine that also runs BrainStream and connect it to BrainStream with <tt>connect_brainstream_client('localhost')</tt>.

The computer running BrainStream should make ports 5001 - 5002 available, as these are used to install all clients.

<div id="LockingMechanism"></div>

== Locking mechanism for global variables ==

If multiple Matlab sessions would simultanously make changes to the same [[BrainStreamImportantConcepts#SecVariables|global variable]], this could lead to conflicts. For this reason, BrainStream locks variables that have been retrieved from the global variables, which prevents other Matlab sessions from accessing this variable. Locking only occurs when the content of the variable will be changed, i.e. when a [[BrainStreamImportantConcepts#GetPut|put]], [.DocsSectionsImportantConcepts#GetPut save] or [[BrainStreamImportantConcepts#ModVars|modification]] action is defined for the variable. In contrast, if a variable is only used as input for a function, i.e. when only a [[BrainStreamImportantConcepts#GetPut|get]] statement is specified for the variable, it will not be locked. Below, schematic figures illustrate the locking mechanism.

[[File:DocsSectionsParallelMode_Locking1.png|484px|209x]]

''Figure 1: Situation where locking does not influence processing''

In figure 1, a situation is shown where a copy of global variable Var1 is retrieved from the global variables to an event structure at the BrainStream Matlab session. From this moment, global variable Var1 is locked, i.e. it is not accessible for other events. During event 1, the copy of Var1 is modified and the new content is stored in the global variables. Subsequently, Var1 is unlocked. Some time after that, a copy of the new content of Var1 is retrieved from the global variables by a client and locked in the global variables. The variable is again modified, put back into the global variables, and unlocked. In this case, the locking mechanism has no consequences for processing.

[[File:DocsSectionsParallelMode_Locking2.png|484px|215x]]

''Figure 2: Another situation where locking does not influence processing''

In figure 2, another situation is shown. In this case, parallel processing takes place. While the BrainStream Matlab session is modifying variable Var1, this variable is locked. However, the other global variables can still be accessed by other Matlab sessions. In this case, a client session retrieves and modifies variable Var2. In this case, the locking mechanism has no effect on processing either.

[[File:DocsSectionsParallelMode_Locking3.png|488px|215x]]

''Figure 3: Locking mechanism''

Effects of the locking mechanism become visible in the situation shown in figure 3. Variable Var1 is locked while it is being modified at the BrainStream Matlab session. During this time, the client is not allowed to retrieve the content of Var1 from the global variables. All actions associated with Event 2 are delayed until Var1 becomes available (see figure 4).

[[File:DocsSectionsParallelMode_Locking4.png|493px|215x]]

''Figure 4: Actions of Event 2 are delayed''

Although the locking mechanism ensures proper parallel processing, you should try to prevent situations like the one in figure 3 in your experimental design. If parallel sessions have to wait for variables to become unlocked, the processing essentially becomes serial again, thereby undoing the benefits of a parallel design.
== Setting the Matlab search path for clients ==

<div id="ClientsMatlabPath"></div>

Files and folders that are used in your experiment must be on the Matlab search path. When you are using multiple parallel Matlab sessions, each Matlab session may require access to a specific set of files. For example, if you have a client for presenting stimuli to the subject, this client must have access to the functions that take care of the stimulus presentation. Therefore, the required functions must be on the client's search path.

The [[BrainStreamPathsFolders|Paths and Folders]] section of this documentation describes how you can add folders to the Matlab search path of the BrainStream Matlab session. The same procedure can be used for clients. One method of adding folders to the search path is via the [[BrainStreamBuildingExperiments#SecBlock|block file]]. For clients, you can similar to the BrainStream session, specify a cell array of folder names under topic [&lt;client name&gt;] and key MatlabPathAdd:<br />
<tt>
[stim]    %this client is called 'stim'<br />
MatlabPathAdd = ...
::::{fullfile(bs_folder('lib'),'speller'), ... % speller lib folder
::::fullfile(bs_folder('root'),'..','signal_processing')}; 
</tt>

Note: always try to prevent absolute paths, as much as possible define paths derived from the options given by <tt>bs_folder()</tt>

BrainStream adds this/these folders to the clients Matlab path at initialization.

Finally, BrainStream automatically copies the search path from the BrainStream Matlab session to all clients. If your client runs on the same computer and does not need access to folders which are not already on the BrainStream search path, you don't have to manually set the search path for your clients.

<!---End1--->

<!--
* Access control 

-->