Lock Step

Use a Lock step to ensure that only one thread can access a particular resource or data item at a time. For example, when you examine and update the value of a global variable from multiple threads or executions, use a lock to ensure that only one thread examines and updates the variable at a time. Multiple threads waiting to lock an item wait in first-in first-out order for the item to become available.

A thread can lock the same item an unlimited number of times without unlocking it, but to release the lock, the thread must balance each Lock operation with an Unlock operation.
Note When all the threads that use a set of locks reside on the same computer and when all the locks in the set reside on that same computer, TestStand detects and reports a run-time error when deadlock occurs with the locks and threads. To avoid deadlock, a set of locks must follow the same order in every thread, or you must use a Lock operation to specify an array of lock names or references that includes all the locks a thread requires. You can also use the Synchronization panel on the Properties tab of the Step Settings pane to create a lock around a single step.

Configuring the Step

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

Step Properties

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

  • Step.Result.TimeoutOccurred —Exists only when you configure the step for the Lock operation. TestStand sets the value to True when the lock operation times out.
    Note If you configure the step to use the Lock 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 Lock Name expression for the Create operation and the Lock Name or Reference expression for all other Lock operations. For the Lock operation, the expression can also specify an array of names or references.
  • Step.LifetimeRefExpr —The object reference expression for the Lock Reference Lifetime or the Lock Operation Lifetime when you set either lifetime to Use Object Reference.
  • Step.TimeoutEnabled —The Timeout Enabled setting for the Lock operation.
  • Step.TimeoutExpr —The Timeout expression, in seconds, for the Lock operation.
  • Step.ErrorOnTimeout —The Timeout Causes Run-Time Error setting for the Lock operation.
  • Step.AlreadyExistsExpr —Contains the Already Exists expression for the Create operation or the Lock Exists expression for the Get Status operation.
  • Step.NumThreadsWaitingExpr —The Number of Threads Waiting to Lock the Lock expression for the Get Status operation.
  • Step.Operation —A value that specifies the operation for the step to perform. The valid values are 0 = Create, 1 = Lock, 2 = Early Unlock, and 3 = Get Status.
  • 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.LockLifetime —A value that specifies the lifetime setting to use for the Lock operation. The valid values are 0 = Same as Sequence, 1 = Same as Thread, 2 = Use Object Reference, and 3 = Same as Execution.
  • Step.CreateIfDoesNotExist —The Create If Does Not Exist setting for the Lock operation.

See Also

Restricting Execution Flow with Lock Steps (Example)

Synchronization Step Types

Thread-Safety of the PropertyObject API and TestStand Variables