#include <mxtimerkm.h>

Collaboration diagram for _MdTimer:

[legend]

Public Member Functions
	_MdTimer (VOID)

	~_MdTimer (VOID)

BOOLEAN	IsInSystemQueue (VOID)

_Must_inspect_result_ NTSTATUS	Initialize (__in_opt PVOID TimerContext, __in MdDeferredRoutine TimerCallback, __in LONG Period)

BOOLEAN	Start (__in LARGE_INTEGER DueTime, __in ULONG TolerableDelay)

_Must_inspect_result_ BOOLEAN	Stop (VOID)

VOID	TimerCallback (VOID)

BOOLEAN	StartWithReturn (__in LARGE_INTEGER DueTime, __in ULONG TolerableDelay)

Static Public Member Functions
static VOID CALLBACK	s_MdWorkCallback (__inout PTP_CALLBACK_INSTANCE Instance, __inout_opt PVOID Context, __inout PTP_WORK Work)

static VOID CALLBACK	s_MdTimerCallback (__inout PTP_CALLBACK_INSTANCE Instance, __inout_opt PVOID Context, __inout PTP_TIMER Timer)

Public Attributes
LONG	m_Period

BOOLEAN	m_IsExtTimer

union {
struct {
MdDeferredRoutine m_TimerCallback

KTIMER KernelTimer

KDPC TimerDpc

}

struct {
MdExtCallback m_ExTimerCallback

PEX_TIMER m_KernelExTimer

}

};

PVOID	m_TimerContext

PTP_TIMER	m_TimerHandle

PTP_WORK	m_WorkObject

BOOL	m_CallbackStartedRunning

BOOL	m_TimerWasStarted

Detailed Description

Definition at line 37 of file mxtimerkm.h.

Constructor & Destructor Documentation

◆ _MdTimer()

_MdTimer::_MdTimer ( VOID )

inline

Definition at line 59 of file mxtimerum.h.

    {
        m_TimerHandle = NULL;
        m_WorkObject = NULL;
        m_TimerCallback = NULL;
        m_TimerContext = NULL;
        m_Period = 0;
        m_CallbackStartedRunning = FALSE;
        m_TimerWasStarted = FALSE;
    }

◆ ~_MdTimer()

_MdTimer::~_MdTimer ( VOID )

inline

Definition at line 72 of file mxtimerum.h.

    {
        //
        // Release the timer object
        //
        if (m_TimerHandle)
        {
            CloseThreadpoolTimer(m_TimerHandle);
            m_TimerHandle = NULL;
        }
 
        //
        // Release the work object
        //
        if (m_WorkObject)
        {
            CloseThreadpoolWork(m_WorkObject);
            m_WorkObject = NULL;
        }
    }

Member Function Documentation

◆ Initialize()

_Must_inspect_result_ NTSTATUS _MdTimer::Initialize	(	__in_opt PVOID	TimerContext,
		__in MdDeferredRoutine	TimerCallback,
		__in LONG	Period
	)

inline

Definition at line 142 of file mxtimerum.h.

    {
        NTSTATUS ntStatus = STATUS_SUCCESS;
 
        m_TimerCallback = TimerCallback;
        m_TimerContext = TimerContext;
        m_Period = Period;
 
        //
        // Create the timer object
        //
        m_TimerHandle = CreateThreadpoolTimer(_MdTimer::s_MdTimerCallback,
                                              this,
                                              NULL);
        if (NULL == m_TimerHandle)
        {
            ntStatus = WinErrorToNtStatus(GetLastError());
        }
 
        //
        // Create the work object
        //
        if (NT_SUCCESS(ntStatus))
        {
            m_WorkObject = CreateThreadpoolWork(_MdTimer::s_MdWorkCallback,
                                                this,
                                                NULL);
            if (NULL == m_WorkObject)
            {
                ntStatus = WinErrorToNtStatus(GetLastError());
            }
        }
 
        return ntStatus;
    }

◆ IsInSystemQueue()

BOOLEAN _MdTimer::IsInSystemQueue ( VOID )

inline

Definition at line 96 of file mxtimerum.h.

    {
        //
        // Timer was not started since it was created or since
        // it was last stopped, so it can't be in the system timer queue.
        //
        if (!m_TimerWasStarted) {
            return FALSE;
        }
 
        //
        // Periodic timers are always in the system timer queue.
        //
        if (m_Period != 0) {
            return TRUE;
        }
 
        //
        // Non-periodic timer:
        //
        // At this point, the timer callback function has either been canceled or
        // has finished running. Examine the m_CallbackStartedRunning value to see
        // which one of these happened.
        //
        if (m_CallbackStartedRunning)
        {
            //
            // Timer cancellation was too late. Timer callback already started
            // running and the timer was removed from the system timer queue.
            //
            return FALSE;
        }
        else
        {
            //
            // Timer cancellation happened on time and prevented the timer callback
            // from running.
            //
            return TRUE;
        }
    }

Referenced by Start(), and Stop().

◆ s_MdTimerCallback()

static VOID CALLBACK _MdTimer::s_MdTimerCallback	(	__inout PTP_CALLBACK_INSTANCE	Instance,
		__inout_opt PVOID	Context,
		__inout PTP_TIMER	Timer
	)

inlinestatic

Definition at line 305 of file mxtimerum.h.

    {
        struct _MdTimer *pThis = NULL;
 
        UNREFERENCED_PARAMETER(Instance);
        UNREFERENCED_PARAMETER(Timer);
 
        pThis = (struct _MdTimer*) Context;
 
        //
        // First, indicate that the callback has started running
        //
        pThis->m_CallbackStartedRunning = TRUE;
 
        //
        // Post a work object to execute the callback function supplied by the
        // user of MxTimer.
        //
        // We do not execute the user-supplied callback here because we could
        // run into a deadlock if the user is trying to cancel the timer by
        // calling MxTimer::Stop. MxTimer::Stop actually blocks waiting for
        // MdTimer::s_MdTimerCallback to finish executing, so that it can know
        // where its attempt to cancel the timer was successful. If we were to
        // execute the user's callback in MdTimer::s_MdTimerCallback, the user
        // would have to be careful not to call MxTimer::Stop while holding a
        // lock that the user's callback tries to acquire. In order to avoid
        // imposing such a restriction on the user, we allow
        // MdTimer::s_MdTimerCallback to return immediately after posting a
        // work object to run the user's callback.
        //
        SubmitThreadpoolWork(pThis->m_WorkObject);
 
        return;
    }

Referenced by Initialize().

◆ s_MdWorkCallback()

static VOID CALLBACK _MdTimer::s_MdWorkCallback	(	__inout PTP_CALLBACK_INSTANCE	Instance,
		__inout_opt PVOID	Context,
		__inout PTP_WORK	Work
	)

inlinestatic

Definition at line 286 of file mxtimerum.h.

    {
        struct _MdTimer *pThis = NULL;
 
        UNREFERENCED_PARAMETER(Instance);
        UNREFERENCED_PARAMETER(Work);
 
        pThis = (struct _MdTimer*) Context;
        pThis->TimerCallback();
 
        return;
    }

Referenced by Initialize().

◆ Start()

BOOLEAN _MdTimer::Start	(	__in LARGE_INTEGER	DueTime,
		__in ULONG	TolerableDelay
	)

inline

Definition at line 183 of file mxtimerum.h.

    {
        BOOLEAN bRetVal;
        FILETIME dueFileTime;
 
        if (m_TimerWasStarted) {
            //
            // Cancel the previously pended timer callback,
            // we want it to execute after a full period elapsed.
            //
            WaitForThreadpoolTimerCallbacks(m_TimerHandle, TRUE);
        }
 
        //
        // Return TRUE if the timer is in the system timer queue.
        //
        bRetVal = IsInSystemQueue();
 
        //
        // This is a fresh start for the timer, so clear the flag that the
        // timer callback function may have previously set.
        //
        m_CallbackStartedRunning = FALSE;
 
        //
        // Set the timer started flag.
        //
        m_TimerWasStarted = TRUE;
 
        //
        // Copy the due time into a FILETIME structure
        //
        dueFileTime.dwLowDateTime = DueTime.LowPart;
        dueFileTime.dwHighDateTime = (DWORD) DueTime.HighPart;
 
        //
        // Start the timer
        //
        SetThreadpoolTimer(m_TimerHandle,
                           &dueFileTime,
                           (DWORD) m_Period,
                           TolerableDelay);
 
        return bRetVal;
    }

◆ StartWithReturn()

BOOLEAN _MdTimer::StartWithReturn	(	__in LARGE_INTEGER	DueTime,
		__in ULONG	TolerableDelay
	)

inline

Definition at line 345 of file mxtimerum.h.

    {
        return Start(DueTime, TolerableDelay);
    }

◆ Stop()

_Must_inspect_result_ BOOLEAN _MdTimer::Stop ( VOID )

inline

Definition at line 234 of file mxtimerum.h.

    {
        BOOLEAN bRetVal;
 
        bRetVal = IsInSystemQueue();
 
        //
        // Stop the timer
        //
        SetThreadpoolTimer(m_TimerHandle,
                           NULL, // pftDueTime
                           0, // msPeriod
                           0 // msWindowLength
                           );
 
        //
        // Cancel pending callbacks that have not yet started to execute and wait
        // for outstanding callbacks to complete.
        //
        WaitForThreadpoolTimerCallbacks(m_TimerHandle,
                                        TRUE // cancel pending callbacks
                                        );
 
        //
        // Reset the timer started flag.
        //
        m_TimerWasStarted = FALSE;
 
        return bRetVal;
    }

◆ TimerCallback()

VOID _MdTimer::TimerCallback ( VOID )

inline

Definition at line 268 of file mxtimerum.h.

    {
        //
        // Invoke the user's callback function
        //
        m_TimerCallback(NULL, /* Reserved1 */
                        m_TimerContext,
                        NULL, /* Reserved2 */
                        NULL /* Reserved3 */
                        );
 
        return;
    }