IoInitializeRemoveLock

The IoInitializeRemoveLock routine initializes a remove lock for a device object.

VOID
  IoInitializeRemoveLock(
    IN PIO_REMOVE_LOCK  Lock,
    IN ULONG  AllocateTag,
    IN ULONG  MaxLockedMinutes,
    IN ULONG  HighWatermark
    );

Parameters

Lock

Pointer to a caller-supplied IO_REMOVE_LOCK structure that this routine initializes with information about the lock, including a counter and a synchronization event. A driver writer must allocate this structure as part of the device object's device extension.

AllocateTag

Specifies a tag to identify the creator of the lock. Driver writers typically use a 4-character string, specified in reverse order, like the tags used for ExAllocatePoolWithTag.

The I/O system only uses this parameter on checked builds.

MaxLockedMinutes

Specifies the maximum number of minutes that this lock should be held. A value of zero means there is no limit. This value is typically used during debugging to identify a driver routine that holds the lock longer than expected.

The I/O system only uses this parameter on checked builds. If the lock is held for more than MaxLockedMinutes on a checked build, the system asserts.

HighWatermark

Specifies the maximum number of outstanding acquisitions allowed on the lock. Use 0 to specify no maximum. HighWatermark must be <= 0x7FFFFFFF.

The I/O system only uses this parameter on checked builds. If the lock is acquired HighWatermark times on a checked build, the system asserts.

Return Value

None

Headers

Declared in ntddk.h. Include ntddk.h.

Comments

A driver can use a remove lock to track outstanding I/O operations on a device and to determine when the driver can delete its device object in response to an IRP_MN_REMOVE_DEVICE request.

Before calling IoInitializeRemoveLock, a driver should allocate an IO_REMOVE_LOCK structure in its device extension. A driver typically calls IoInitializeRemoveLock in its AddDevice routine, when the driver initializes the rest of the device extension for a device object.

Because the driver stores the IO_REMOVE_LOCK structure in the device extension of a device object, the remove lock is deleted when the driver deletes the device extension as part of processing an IRP_MN_REMOVE_DEVICE request.

Callers of IoInitializeRemoveLock must be running at IRQL = PASSIVE_LEVEL.

For more information, see Using Remove Locks.

See Also

IoAcquireRemoveLock, IoReleaseRemoveLock, IoReleaseRemoveLockAndWait