Wait Debugging Functions

Microsoft® DirectShow® provides several functions for debugging infinite waits.

Declaration: Wxdebug.h

In retail builds, the DbgWaitForMultipleObjects and DbgWaitForSingleObject functions work like their Microsoft® Win32® counterparts, WaitForMultipleObjects and WaitForSingleObject, with infinite time-out intervals.

In debug builds, these functions use a global time-out value. If the time-out expires, the function triggers an assert. The following registry key specifies the time-out value, in milliseconds:

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\TIMEOUT

If the key does not exist, the time-out value defaults to INFINITE. You can use the DbgSetWaitTimeout function to override the registry entry.

Function	Description
DbgSetWaitTimeout	Sets the debugging time-out value.
DbgWaitForMultipleObjects	Waits for any (or all) of the specified objects to be signaled.
DbgWaitForSingleObject	Waits for an object to become signaled.

DbgSetWaitTimeout

---

Wait Debugging Functions

Sets the debugging time-out value. Ignored in retail builds.

Syntax

void DbgSetWaitTimeout(
    DWORD dwTimeout
);

Parameters

dwTimeout

Time-out value in milliseconds, or INFINITE to wait indefinitely.

Remarks

In debug builds, the DbgWaitForMultipleObjects and DbgWaitForSingleObject functions use this value as the time-out interval.

DbgWaitForMultipleObjects

---

Wait Debugging Functions

Waits for any (or all) of the specified objects to be signaled.

In a debug build, this function triggers an assert if the time-out interval expires before the objects are signaled. To set the time-out interval, call the DbgSetWaitTimeout function.

In a retail build, this function is equivalent to the WaitForMultipleObjects function with a time-out interval of INFINITE.

Syntax

DWORD DbgWaitForMultipleObjects(
    DWORD nCount,
    CONST HANDLE *lpHandles,
    BOOL bWaitAll
);

Parameters

nCount

Number of objects.

lpHandles

Array of handles to objects, of size nCount.

bWaitAll

Boolean value that specifies whether to wait for all of the objects. If TRUE, the function waits for all of the objects to be signaled. Otherwise, it waits for at least one object to be signaled.

DbgWaitForSingleObject

---

Wait Debugging Functions

Waits for an object to become signaled.

In a debug build, this function triggers an assert if the time-out interval expires before the object is signaled. To set the time-out interval, call the DbgSetWaitTimeout function.

In a retail build, this function is equivalent to the WaitForSingleObject function with a time-out interval of INFINITE.

Syntax

DWORD DbgWaitForSingleObject(
    HANDLE h
);

Parameters

h

Handle to the object.