Changes

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

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

== Starting clients ==

== 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 />

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:

<tt>

<pre>connect_brainstream_client('ip_address') % specify the ip-address of the computer running [[BrainStream|Brain Stream]]</pre>

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>.

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>.

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.

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:BrainStreamParallelMode.Locking1.png|484px|209x]]

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

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

''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.

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:BrainStreamParallelMode.Locking2.png|484px|215x]]

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

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

''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.

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:[BrainStreamParallelMode.Locking3.png|488px|215x]]

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

''Figure 3: Locking mechanism''

''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).

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:BrainStreamParallelMode.Locking4.png|493px|215x]]

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

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

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

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.

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:

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 />

<pre>[stim]    %this client is called 'stim'

<tt>

[[MatlabPathAdd|Matlab Path Add]] = {fullfile(bs_folder('lib'),'speller'), ... % speller lib folder

[stim]    %this client is called 'stim'<br />

                fullfile(bs_folder('root'),'..','signal_processing')};  

MatlabPathAdd = ...

</pre>

::::{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>

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