ExAcquireSharedWaitForExclusive function (wdm.h)

Article
04/18/2022

The ExAcquireSharedWaitForExclusive routine acquires the given resource for shared access if shared access can be granted and there are no exclusive waiters.

Syntax

BOOLEAN ExAcquireSharedWaitForExclusive(
  [in, out] PERESOURCE Resource,
  [in]      BOOLEAN    Wait
);

Parameters

[in, out] Resource

A pointer to the resource to be acquired for shared access.

[in] Wait

Specifies the routine's behavior whenever the resource cannot be acquired immediately. If TRUE, the caller is put into a wait state until the resource can be acquired. If FALSE, the routine immediately returns, regardless of whether the resource can be acquired.

Return value

ExAcquireSharedWaitForExclusive returns TRUE if the requested access is granted or an exclusive owner releases the resource. This routine returns FALSE if the input Wait is FALSE and shared access cannot be granted immediately.

Remarks

Most drivers should use ExAcquireResourceSharedLite instead of ExAcquireSharedWaitForExclusive.

The caller can release the resource by calling either ExReleaseResourceLite or ExReleaseResourceForThreadLite.

If shared access cannot be granted immediately, the caller can wait for other threads to acquire and release exclusive ownership of the resource.

Whether or when the caller is given shared access to the given resource depends on the following:

If the resource is currently unowned, shared access is granted immediately to the current thread.
If the caller already has exclusive access to the resource, the current thread is granted the same type of access recursively.
If the resource is currently owned as shared and there are no pending attempts to acquire exclusive access, shared access is granted to the caller immediately.
If the resource is currently owned as shared but there is a pending attempt to acquire exclusive access, the caller either is put into a wait state (Wait set to TRUE) or ExAcquireSharedWaitForExclusive returns FALSE.
When the current thread waits to acquire the resource until after a pending exclusive ownership has been released, ExAcquireSharedWaitForExclusive returns TRUE when the current thread is granted shared access to the resource and resumes execution.

The behavior of ExAcquireSharedWaitForExclusive is identical to that of ExAcquireResourceSharedLite unless the calling thread already owns the resource as shared and there are exclusive waiters. In that case, ExAcquireSharedWaitForExclusive allows the exclusive waiters to acquire exclusive ownership of the resource.

If the caller specifies TRUE for the Wait parameter, the caller blocks until another thread frees the resource on behalf of the caller, using ExReleaseResourceForThread. Driver writers must be careful to ensure that another thread actually releases the resource; otherwise the caller is deadlocked. ExAcquireResourceSharedLite does not have this property, so drivers should use that routine unless they require the particular behavior of ExAcquireSharedWaitForExclusive.

Normal kernel APC delivery must be disabled before calling this routine. Disable normal kernel APC delivery by calling KeEnterCriticalRegion. Delivery must remain disabled until the resource is released, at which point it can be reenabled by calling KeLeaveCriticalRegion. For more information, see Disabling APCs.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 2000.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs(storport), IrqlExApcLte3(wdm), SpNoWait(storport), WithinCriticalRegion(storport), WithinCriticalRegion(storport), WithinCriticalRegion(wdm)