Introduction to ERESOURCE Routines

The system provides routines to acquire and release ERESOURCE structures, as well as to examine their current state.

Acquiring and Releasing an ERESOURCE Structure

Drivers can use the ERESOURCE structures to implement exclusive/shared synchronization. Exclusive/shared synchronization works as follows:

• Any number of threads can acquire an ERESOURCE as shared.

• Only one thread can acquire an ERESOURCE exclusively. The ERESOURCE can only be acquired exclusively if no threads have already acquired it as shared.

A thread that cannot currently acquire an ERESOURCE can optionally be put in a wait state until the ERESOURCE can be acquired. The system maintains two lists of threads that are waiting for an ERESOURCE: a list of exclusive waiters and a list of shared waiters.

A typical use for exclusive/shared synchronization is to implement a read/write lock. A read/write lock allows several threads to perform a read operation, but only one thread can write at a time. This can be implemented directly in terms of acquiring an ERESOURCE.

A driver allocates the storage for an ERESOURCE and initializes it with ExInitializeResourceLite. The system maintains a list of all ERESOURCE structures in use. When the driver no longer requires a particular ERESOURCE, it must call ExDeleteResourceLite to delete it from the system's list. The driver can also reuse an ERESOURCE by calling ExReinitializeResourceLite.

Drivers can perform the following basic operations on an ERESOURCE:

• Acquire an ERESOURCE as shared with ExAcquireResourceSharedLite. This routine acquires the resource only if the resource has not been acquired exclusively and there are no exclusive waiters.

• Acquire an ERESOURCE exclusively with ExAcquireResourceExclusiveLite. This routine acquires the resource as long as it has not been acquired either exclusively or as shared.

• Convert an exclusive acquisition to a shared acquisition with ExConvertExclusiveToSharedLite.

• Release an acquired resource with ExReleaseResourceLite.

The Wait parameter of ExAcquireResourceSharedLite and ExAcquireResourceExclusiveLite determines whether the current thread waits for the ERESOURCE to be acquired. If you specify a value of FALSE and the ERESOURCE cannot be acquired, then the routine returns FALSE. If you specify a value of TRUE, then the current thread is put on the appropriate wait list for the ERESOURCE.

Examining the State of an ERESOURCE Structure

A driver can also determine the current state of an ERESOURCE, as follows:

• Use ExIsResourceAcquiredLite or ExIsResourceAcquiredSharedLite to determine if the ERESOURCE has already been acquired as either shared or exclusive. Use ExIsResourceAcquiredExclusiveLite to check whether the ERESOURCE has been specifically acquired exclusively.

• Use ExGetSharedWaiterCount to determine the number of shared waiters for the ERESOURCE, and use ExGetExclusiveWaiterCount to determine the number of exclusive waiters for the ERESOURCE.