Added in v2.0


Syntax: #SECTION name {commands}
Related: %section

Creates a protected named section of code. When multiple threads are running, only a single thread can execute the same named section at a time. If another thread is currently in the middle of executing code within the same named section, then the current thread is suspended until the other thread is finished.

There is no way to timeout or abort a wait for a named section. But you can use the %section function to determine how many threads are executing or waiting on the named section.

Typically, you would use a named section when accessing a global resource (such as a variable) when other threads might be running in parallel. For example, consider the following script:

#IF (@varname = 1) {#SHOW "Value is:" @varname}

Normally you might expect that this will always display the "Value is: 1" result. However, if another thread is running in parallel and it changes varname=2, then this other thread might execute after the #IF test, but before the #SHOW command. In this case, you would see "Value is: 2", which you might normally think is impossible.

The solution to this is to put both threads within the same named section. The first script would look like this:

#SECTION VarSection {
#IF (@varname = 1) {#SHOW "Value is:" @varname}

and the other thread's script would look like this:

#SECTION VarSection {varname = 2}

Since each #SECTION command has the same name (VarSection), only one of them will execute at a time. So now you will always get the expected "Value is: 1" result.

See the help topic on Threading for more detail on using threads properly. Unless you are specifically suspending threads using commands such as #WAIT, #WAITFOR, etc then you normally do not need to worry about any of this complexity. TeSSH normally executes triggers in sequence and not in parallel to avoid these complexities.

NOTE: Be VERY careful to ensure that the code within the #SECTION executes quickly and does not do anything that would cause the script to pause. For example, DO NOT put other wait commands within a Section, and DO NOT prompt for any user input using #PROMPT, #PICK, etc. Remember that while your script is executing the code in a #SECTION, any other thread that tries to execute the same section will wait. And this cause cause TeSSH to appear to hang while it is waiting.

Add comment

Login or register to post comments