Acquire (function)

Syntax bool = Acquire(Region$, TimeOut&)
Description Acquire a Critical Section with a timeout. If the section is not acquired within the specified timeout, a value of False is returned.

Critical Sections are used in multithreaded application to control reentrancy, protect access global data structures, and provide synchronization. Only one thread of an application can be within a critical section at a time. Since the Basic Control Engine is a multithreaded application, you may need to use critical sections to prevent race type conditions.

Acquire and Release only work with the same process. In other words, two standalone executables cannot protect against each other using this mechanism.

In the Basic Control Engine, when an event occurs, the script is started in parallel with any other currently executing scripts. If two scripts compete for the same resource in your factory (e.g. controlling a pump) you may need to use critical sections to control access.

Unlike a C application, access to public and private variables is controlled automatically by BASIC. That is, if two threads are trying to set and get the value of a variable access to the variable is synchronous. In other words, the thread, which is reading the value, won't get a value, which is half-written by the other thread. However, if you are accessing more than one element of a global data structure and expect another thread to be accessing the data, then you must protect the access with a critical section.

The Basic Control Engine automatically releases any critical sections held by the script when it terminates. While the script is running, you can use the Acquire and Release commands to control when a critical section is released. You must make a call to Release for each call you make to Acquire for a critical section.

Comments
Parameter Description
Region$ String. A unique identifier of the region to be operated on.
TimeOut& Long. The time in milliseconds to wait.
Example Prevent reentry into the routine if the script is already in progress. If the script can't acquire the region immediately, it will exit.
Sub Main()
    if Acquire("DATETIME",0) = FALSE then
       Exit Sub
    end if
    if Date$ <> LastDate then
       LastDate = Date$
       PointSet "DATE",LastDate
    end if
    PointSet "TIME",Time$
    Release "DATETIME"
End Sub