Semaphore Lock

This System tool attempts to acquire a lock on the resource semaphore named in the resource name parameter.

If the resource has not been initialized, the first use of a semaphore lock tool initializes the semaphore and the Shared Lock Limit.

Note: Locks are released when the handler placing them finishes. They can not be locked by one handler and released by another. They can be locked by subroutines and kept alive by passing Semaphore Lock Handle to the subroutine, and keeping the returned handle in scope until the calling handler completes.

Multiple calls to lock a resource by a handler and its subroutines will not place any additional locks. Instead a reference count is incremented. The reference count will be used to insure that the resource is not unlocked until a matching number of Unlocks is called.

Regardless of the number of times the lock is placed on the resource by the handler, when the handler exits, the resource lock is freed for another handler to access.

Inputs

Semaphore Resource Name

Identifies the resource to be locked.

Note: A named semaphore is not used. The name is used only to lookup and identify the correct semaphore object in memory. This is not a named semaphore that can be shared with other NT processes.

Shared Access Limit

Number of locks that can be placed against the semaphore at the same time. When this limit is reached, all others must wait until a lock is released. The default limit is 1.

Wait Timeout Milliseconds

Number of milliseconds the lock tool will wait for a lock before giving up and taking the timeout path. The default timeout is 500 milliseconds.

Outputs

Semaphore Lock Handle

This is the handle returned when a lock is successful. This handle must be used with the Semaphore Unlock tool. The handle is also part of the mechanism that insures that a lock will be released when the handler exits.

Exit Paths:

Success

Lock was given on resource.

Failure

Some type of internal error kept the locking process from succeeding. Trace logs should be checked for error messages.

Timeout

Lock was not acquired within the specified timeout limit.