Microsoft DirectX 8.0

CAMSchedule Class

Scheduler for reference clocks.

Declaration: Schedule.h.

This helper object maintains a list of advise requests for a reference clock. The CBaseReferenceClock class uses it to help schedule advise requests. Clocks use this object in the following manner:

  1. The clock creates a worker thread to handle scheduling.
  2. The worker thread calls the GetEvent method to retrieve an event handle from the scheduler. It waits on this event, initially with an infinite time-out.
  3. To shedule a new advise request, the clock calls the AddAdvisePacket method. An advise request can be one-shot or periodic. The scheduler keeps the list of requests in time order.
  4. If a request is added to the front of the list, the scheduler signals the event. (The list is empty at first, so the first request is guaranteed to signal the event.)
  5. When the event is signaled, the worker thread calls the Advise method, specifying the current reference time. If any pending requests have expired, the scheduler dispatches them.
  6. The Advise method returns the time of the next request. The worker thread uses this value to calculate a new time-out value.
  7. Steps 2–6 repeat indefinitely.
  8. To terminate the worker thread, the clock sets an internal flag and signals the event.

In step 2, either the event is signaled, or the wait times out. If the event is signaled, it means that a new request was added to the front of the list. The worker thread must calculate a new time-out value. On the other hand, if the wait times out, it means that an advise request has come due and must be dispatched. The call to Advise in step 5 handles both cases.

Public Methods
CAMScheduleConstructor method.
~CAMScheduleDestructor method. Virtual.
GetAdviseCountRetrieves the number of pending advise requests.
GetNextAdviseTimeRetrieves the time of the next advise request.
AddAdvisePacketAdds an advise request to the list of pending requests.
UnadviseRemoves an advise request.
AdviseDispatches all requests that are scheduled for a specified time or earlier.
GetEventRetrieves an event handle, which is used to signal a change in the next advise time.

CAMSchedule::AddAdvisePacket

CAMSchedule Class

Adds an advise request to the list of pending requests.

Syntax

DWORD AddAdvisePacket(
    const REFERENCE_TIME& time1,
    const REFERENCE_TIME& time2,
    HANDLE hNotify,
    BOOL bPeriodic
);

Parameters

time1
Requested time for the advise.
time2
For periodic advise requests, the time between notifications. This parameter is ignored if bPeriodic is FALSE.
hNotify
Handle to a semaphore if bPeriodic is TRUE, or handle to an event if bPeriodic is FALSE.
bPeriodic
Boolean value that specifies whether to add a periodic notification or a one-shot notification. If TRUE, the notification is periodic; the time2 parameter specifies the time between notifications. If FALSE, the notification occurs only once.

Return Value

Returns an identifier for the advise request (the "cookie"). If the method fails, the return value is zero.

CAMSchedule::Advise

CAMSchedule Class

Dispatches all requests that are scheduled for a specified time or earlier.

Syntax

REFERENCE_TIME Advise(
    const REFERENCE_TIME& rtTime
);

Parameters

rtTime
Value that specifies the current reference time.

Return Value

Returns the reference time of the next scheduled advise request, or MAX_TIME if there are none left.

Remarks

When the clock calls this method, it specifies the current reference time. The scheduler determines which advise requests have expired, if any, and dispatches them. If a one-shot request expires, the scheduler deletes it. If a periodic request expires, the scheduler re-schedules it for the next advise time. The method returns the time of the next pending request.

To dispatch an advise request, the scheduler signals the event or semaphore given in the hNotify parameter of the AddAdvisePacket method.

CAMSchedule::CAMSchedule

CAMSchedule Class

Constructor method.

Syntax

CAMSchedule(
    HANDLE hEvent
);

Parameters

hEvent
Handle to an auto-reset event.

CAMSchedule::~CAMSchedule

CAMSchedule Class

Destructor method.

Syntax

~CAMSchedule(void);

CAMSchedule::GetAdviseCount

CAMSchedule Class

Retrieves the number of pending advise requests.

Syntax

DWORD GetAdviseCount(void);

Return Value

Returns the number of pending advise requests.

CAMSchedule::GetEvent

CAMSchedule Class

Retrieves an event handle, which is used to signal a change in the next advise time.

Syntax

HANDLE GetEvent(void);

Return Value

Returns a handle to an event.

Remarks

If the next advise time changes—in other words, if a new advise request is added to the front of the list—the scheduler signals this event. The clock should call the Advise method to determine the next advise time.

CAMSchedule::GetNextAdviseTime

CAMSchedule Class

Retrieves the time of the next advise request.

Syntax

REFERENCE_TIME GetNextAdviseTime(void);

Return Value

Returns the reference time of the next advise request, or MAX_TIME no requests are scheduled.

CAMSchedule::Unadvise

CAMSchedule Class

Removes an advise request.

Syntax

HRESULT Unadvise(
    DWORD dwAdviseCookie
);

Parameters

dwAdviseCookie
Identifier of the advise request, returned by the AddAdvisePacket method.

Return Value

Returns one of the HRESULT values shown in the following table.

S_FALSENot found
S_OKSuccess