Microsoft DirectX 8.0

Critical Section Debugging Functions

These functions help to debug critical sections in your code, which can make it easier to find the cause of a deadlock. These functions use the CCritSec helper class.

Declaration: Wxutil.h.

CritCheckInReturns TRUE if the current thread owns the specified critical section.
CritCheckOutReturns FALSE if the current thread owns the specified critical section.
DbgLockTraceEnables or disables debug logging for a given critical section.

CritCheckIn

Critical Section Debugging Functions

Returns TRUE if the current thread is the owner of the specified critical section.

Syntax

BOOL WINAPI CritCheckIn(
    CCritSec *pcCrit
);

Parameters

pcCrit
Pointer to a CCritSec critical section.

Return Value

In debug builds, returns TRUE if the current thread is the owner of this critical section, or FALSE otherwise. In retail builds, always returns TRUE.

Remarks

This function is especially useful within the ASSERT macro, to test whether a thread owns a given lock.

The following code example shows how to use this function:

{
    CCritSec MyLock;  // Critical section is not locked yet.
    
    ASSERT(CritCheckIn(&MyLock)); // This assert will fire.

    // Lock the critical section.    
    CAutoLock cObjectLock(&MyLock);
     
    ASSERT(CritCheckIn(&MyLock)); // This assert will not fire.

} // Lock goes out of scope here.

CritCheckOut

Critical Section Debugging Functions

Returns FALSE if the current thread is the owner of the specified critical section.

Syntax

BOOL WINAPI CritCheckOut(
    CCritSec *pcCrit
);

Parameters

pcCrit
Pointer to a CCritSec critical section.

Return Value

In debug builds, returns FALSE if the current thread is the owner of this critical section, or TRUE otherwise. In retail builds, always returns TRUE.

Remarks

This function is the inverse of the CritCheckIn function. If CritCheckIn returns TRUE, CritCheckOut returns FALSE, and vice versa.

DbgLockTrace

Critical Section Debugging Functions

Enables or disables debug logging of a given critical section.

Syntax

void WINAPI DbgLockTrace(
    CCritSec *pcCrit,
    BOOL fTrace
);

Parameters

pcCrit
Pointer to a CCritSec critical section.
fTrace
Value specifying whether logging is enabled. Use TRUE to enable logging or FALSE to disable it.

Remarks

Use this function to trace a specific critical section. By default, debug logging of critical sections is disabled, because of the large number of critical sections.

To trace a critical section, perform the following steps:

  1. Define DEBUG before you include the DirectShow headers.
  2. Enable debug logging for critical sections, by calling DbgSetModuleLevel with the LOG_LOCKING flag.
  3. Call DbgLockTrace on the critical section you want to trace.

The following code example shows how to trace a critical section:

DbgInitialise(g_hInst);
DbgSetModuleLevel(LOG_LOCKING, 3);

{
    CCritSec MyLock;
    DbgLockTrace(&MyLock, TRUE);
    
    CAutoLock cObjectLock(&MyLock);

    // Protected section of code.    
    DbgOutString("This code is inside a critical section.\n");

} // Lock goes out of scope here.

DbgTerminate();

The debug output will look similar to the following:

Example.exe(tid 360)     2012 : Thread 864 now owns lock 12fc2c
This code is inside a critical section.
Example.exe(tid 360)     4887 : Thread 864 releasing lock 12fc2c

If DEBUG is not defined when you include the DirectShow headers, the DbgLockTrace function has no effect.