Microsoft DirectX 8.0 |
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:
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 | |
---|---|
CAMSchedule | Constructor method. |
~CAMSchedule | Destructor method. Virtual. |
GetAdviseCount | Retrieves the number of pending advise requests. |
GetNextAdviseTime | Retrieves the time of the next advise request. |
AddAdvisePacket | Adds an advise request to the list of pending requests. |
Unadvise | Removes an advise request. |
Advise | Dispatches all requests that are scheduled for a specified time or earlier. |
GetEvent | Retrieves an event handle, which is used to signal a change in the next advise time. |
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.
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.
Constructor method.
Syntax
CAMSchedule( HANDLE hEvent );
Parameters
- hEvent
- Handle to an auto-reset event.
Destructor method.
Syntax
~CAMSchedule(void);
Retrieves the number of pending advise requests.
Syntax
DWORD GetAdviseCount(void);
Return Value
Returns the number of pending advise requests.
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 changesin other words, if a new advise request is added to the front of the listthe scheduler signals this event. The clock should call the Advise method to determine the next advise time.
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.
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_FALSE Not found S_OK Success