Use a Semaphore step to limit concurrent access to a resource to a specific number of threads. A semaphore stores a numeric count, and threads can increment (release) or decrement (acquire) the count as long as the count stays equal to or greater than zero. When a decrement causes the count to drop below zero, the thread that attempts to decrement the count blocks until the count increases. When multiple threads wait to decrement a semaphore and another thread increments the count, the semaphore unblocks the threads in first-in first-out order.

A semaphore with an initial count of one behaves like a lock because a one-count semaphore restricts access to a single thread at a time. Unlike a lock, however, a thread cannot acquire a one-count semaphore multiple times without first releasing the semaphore after each acquire. When a thread attempts to acquire the semaphore a second time without releasing it, the count is zero, and the thread blocks.

Configuring the Step

Use the Semaphore Settings edit tab in the TestStand Sequence Editor and the Semaphore Step Configuration dialog box in a TestStand User Interface to configure the Semaphore step.

Step Properties

In addition to the common custom properties , the Semaphore step type defines the following step properties:

• Step.Result.TimeoutOccurred —Exists only when you configure the step for the Acquire operation. TestStand sets the value to True when the Acquire operation times out.
  Note If you configure the step to use the Acquire operation programmatically using the Step.Operation property, you must also create the Step.Result.TimeoutOccurred property using the newProperty( ) method for the step to execute successfully.
• Step.NameOrRefExpr —Contains the Semaphore Name expression for the Create operation and the Semaphore Name or Reference expression for all other Semaphore operations.
• Step.AutoRelease —A Boolean value that specifies whether the Acquire operation automatically performs a release when the Acquire lifetime expires.
• Step.LifetimeRefExpr —The object reference expression for the Semaphore Reference Lifetime or the Acquire Reference Lifetime when you set either lifetime to Use Object Reference .
• Step.TimeoutEnabled —The Timeout Enabled setting for the Acquire operation.
• Step.TimeoutExpr —The Timeout expression, in seconds, for the Acquire operation.
• Step.ErrorOnTimeout —The Timeout Causes Run-Time Error setting for the Acquire operation.
• Step.AlreadyExistsExpr —Contains the Already Exists expression for the Create operation or the Semaphore Exists expression for the Get Status operation.
• Step.InitialCountExpr —The Initial Semaphore Count expression for the Create operation.
• Step.NumThreadsWaitingExpr —The Number of Threads Waiting to Acquire the Semaphore expression for the Get Status operation.
• Step.Operation —A value that specifies the operation for the step to perform. The valid values are 0 = Set Thread Priority and 1 = Get Thread Priority.
• Step.Lifetime —A value that specifies the lifetime setting to use for the Create operation. The valid values are 0 = Same as Sequence, 1 = Same as Thread, 2 = Use Object Reference, and 3 = Same as Execution.
• Step.InitialCountOutExpr —The Initial Semaphore Count expression for the Get Status operation.
• Step.AcquireLifetime —A value that specifies the lifetime setting for the Acquire operation. The valid values are 0 = Same as Sequence, 1 = Same as Thread, and 2 = Use Object Reference. The Acquire operation uses this setting only when Step.AutoRelease is True .
• Step.CurrentCountExpr —The Current Count expression for the Get Status operation.

See Also

Controlling Multi-Threaded Execution Flow with Rendezvous and Semaphore Steps (Example)

Synchronization Step Types