XXX_PreClose (Device Manager) (Compact 2013)
3/26/2014
This function notifies the driver to mark the closing handle as invalid and to wake any sleeping threads.
Syntax
BOOL XXX_PreClose(
DWORD hOpenContext
);
Parameters
- hDeviceContext
[in] Handle to the device context. The XXX_Init (Device Manager) function creates and returns this identifier.
Remarks
If XXX_PreClose is present, XXX_PreDeinit (Device Manager) must also be present or the driver will not load.
Device Manager uses the XXX prefix. When implementing the stream interface, replace XXX with a prefix appropriate for your specific implementation or use undecorated entry point names in conjunction with DEVFLAGS_NAKEDENTRIES. For more information about other valid Flags values, see ActivateDeviceEx.
Threads might block in a driver, and these blocked threads might not be able to release resources associated with the handle or device instance. The following list shows race conditions related to blocked threads not being able to release resources:
- A race condition can occur if Device Manager attempts to unload a device when the device driver's XXX_Deinit (Device Manager) function executes in one thread while another thread attempts to open a handle. In these cases, from the driver's perspective, XXX_Deinit is called before XXX_Open (Device Manager). This might happen during prolonged and heavy CPU loading when drivers are unloading and reloading frequently. When Device Manager calls the XXX_Deinit entry point, drivers should wake threads that are blocked on I/O and free resources associated with the handle or device instance. If Device Manager calls XXX_Open after calling XXX_Deinit, some drivers might crash.
- A similar race condition can occur between I/O operations on one thread and another thread calling CloseHandle. When Device Manager calls the XXX_Close (Device Manager) entry point, drivers should wake threads blocked on that handle and free resources associated with that handle. If Device Manager calls an I/O entry point, such as XXX_IOControl (Device Manager) after calling XXX_Close, some drivers might crash.
To address these race conditions, Device Manager checks for two optional driver entry points, XXX_PreClose and XXX_PreDeinit. These have the same signatures as the XXX_Close and XXX_Deinit entry points. Device Manager first calls XXX_PreClose and waits to call XXX_Close until no external threads are executing in the driver's DLL using the closing handle. Similarly, Device Manager calls XXX_PreDeinit to tell the driver to mark the device instance as invalid and wake sleeping threads. Device Manager calls XXX_Deinit when no external threads are executing in the driver DLL using the handle. Thus, the XXX_PreClose and XXX_PreDeinit entry points allow the driver to separately invalidate handles and wake threads before XXX_Close and XXX_Deinit are called.
See Also
Reference
Stream Interface Driver Functions
ActivateDeviceEx
XXX_Close (Device Manager)
XXX_Deinit (Device Manager)
XXX_Init (Device Manager)
XXX_IOControl (Device Manager)
XXX_Open (Device Manager)
XXX_PreDeinit (Device Manager)