torsten
77c67c12ca
Entire-Metadata: .entire/metadata/fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Session: fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Strategy: manual-commit
120 lines
3.6 KiB
C
120 lines
3.6 KiB
C
/*
|
|
* (c) Copyright, Real-Time Innovations, 2002-2024.
|
|
* All rights reserved.
|
|
*
|
|
* No duplications, whole or partial, manual or electronic, may be made
|
|
* without express written permission. Any such copies, or
|
|
* revisions thereof, must display this notice unaltered.
|
|
* This code contains trade secrets of Real-Time Innovations, Inc.
|
|
*/
|
|
|
|
#ifndef event_timer_h
|
|
#define event_timer_h
|
|
|
|
|
|
#ifndef osapi_type_h
|
|
#include "osapi/osapi_type.h"
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
struct RTINtpTime; /* forward declare to appease the compiler */
|
|
|
|
struct REDAWorker;
|
|
|
|
struct RTIEventTimer;
|
|
|
|
/*e \file
|
|
\brief timer interface
|
|
*/
|
|
|
|
/*e \defgroup RTIEventTimerClass RTIEventTimer
|
|
\ingroup RTIEventModule
|
|
\brief timer interface
|
|
|
|
A timer is a thread specific object used by each event thread to sleep
|
|
for some time, then wake up to perform timed events that have fired.
|
|
At the very least, the event thread will wak up to check if any event
|
|
has fired. While only the event thread may sleep on this timer, any
|
|
thread may try to wake up the event thread. Many OSes provide a interrupt
|
|
to the sleeping thread, and we can provide a "smart" timer using this
|
|
facility. Otherwise, we have no choice but to just put the new event
|
|
into the event thread's queue, and let it keep sleeping, and the
|
|
event thread will then process the queued event the next time it wakes up.
|
|
|
|
All known implementations: RTIEventPolledTimer, RTIEventSmartTimer
|
|
|
|
@see RTIEvent_Timer_Public UML class diagram
|
|
*/
|
|
|
|
|
|
/*e \ingroup RTIEventTimerClass
|
|
\brief Wakeup a timer to reschedule, for example when new events are added.
|
|
|
|
@pre timer started with RTIEventTimerStartFunction
|
|
@return RTI_TRUE on success, RTI_FALSE otherwise
|
|
|
|
@mtsafety Implementation must provide safety. <<multiThreadSafe>>
|
|
|
|
@see RTIEventTimerStartFunction
|
|
*/
|
|
typedef RTIBool
|
|
(*RTIEventTimerWakeupFunction)(struct RTIEventTimer *me);
|
|
|
|
/*e \ingroup RTIEventTimerClass
|
|
\brief Prep the timer in context of the event thread.
|
|
|
|
A timer may be created by any thread, but the the timer may need to
|
|
be initialized for use by the event thread (the only thread that may
|
|
call the sleep method on the timer). We could have gotten rid of this
|
|
by requiring that only the event thread itself create the timer, but
|
|
that would have complicated the system start up sequence, as timer is
|
|
passed to other threads for wakeup.
|
|
|
|
@pre valid args
|
|
@post The timer is ready to sleep.
|
|
@return RTI_TRUE on success, RTI_FALSE otherwise
|
|
@mtsafety The caller guarantees that only the event thread calls this method,
|
|
and that it is called once and only once in its lifetime. <<singleThread_1>>
|
|
*/
|
|
typedef RTIBool
|
|
(*RTIEventTimerStartFunction)(struct RTIEventTimer *me);
|
|
|
|
/*e \ingroup RTIEventTimerClass
|
|
|
|
\brief Try to sleep till given time.
|
|
|
|
@post Calling thread sleeps up to sleep time. It is permissible to
|
|
wake up earlier, such as in smart timer.
|
|
|
|
@param sleepTime \b in. Desired sleep duration.
|
|
@return RTI_TRUE on success, RTI_FALSE otherwise
|
|
|
|
@mtsafety The caller guarantees that only the event thread calls this method
|
|
in single threaded manner. <<singleThread_1>>
|
|
*/
|
|
typedef RTIBool
|
|
(*RTIEventTimerSleepFunction)(struct RTIEventTimer *me,
|
|
const struct RTINtpTime *sleepTime);
|
|
|
|
/*e \ingroup RTIEventTimerClass
|
|
\brief Pure virtual interface
|
|
*/
|
|
struct RTIEventTimer {
|
|
/*e Only the event thread may call this */
|
|
RTIEventTimerStartFunction start;
|
|
/*e Only the event thread may call this */
|
|
RTIEventTimerSleepFunction sleep;
|
|
/*e Any thread except the event thread may call this */
|
|
RTIEventTimerWakeupFunction wakeup;
|
|
};
|
|
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
#endif /* event_timer_h */
|