Mercurial > sdl-ios-xcode
comparison include/SDL_timer.h @ 5113:481dabb098ef
Improved timer implementation
The new timer model is formalized as using a separate thread to handle timer callbacks. This was the case on almost every platform before, but it's now a requirement, and simplifies the implementation and makes it perform consistently across platforms.
Goals:
* Minimize timer thread blocking
* Dispatch timers as accurately as possible
* SDL_AddTimer() and SDL_RemoveTimer() are completely threadsafe
* SDL_RemoveTimer() doesn't crash with a timer that's expired or removed
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Thu, 27 Jan 2011 14:45:06 -0800 |
parents | f7b03b6838cb |
children | b530ef003506 |
comparison
equal
deleted
inserted
replaced
5112:0846f18eb625 | 5113:481dabb098ef |
---|---|
39 extern "C" { | 39 extern "C" { |
40 /* *INDENT-ON* */ | 40 /* *INDENT-ON* */ |
41 #endif | 41 #endif |
42 | 42 |
43 /** | 43 /** |
44 * This is the OS scheduler timeslice, in milliseconds. | 44 * \brief Get the number of milliseconds since the SDL library initialization. |
45 */ | |
46 #define SDL_TIMESLICE 10 | |
47 | |
48 /** | |
49 * This is the maximum resolution of the SDL timer on all platforms. | |
50 */ | |
51 #define TIMER_RESOLUTION 10 /**< Experimentally determined */ | |
52 | |
53 /** | |
54 * Get the number of milliseconds since the SDL library initialization. | |
55 * | 45 * |
56 * Note that this value wraps if the program runs for more than ~49 days. | 46 * \note This value wraps if the program runs for more than ~49 days. |
57 */ | 47 */ |
58 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); | 48 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void); |
59 | 49 |
60 /** | 50 /** |
61 * Wait a specified number of milliseconds before returning. | 51 * \brief Wait a specified number of milliseconds before returning. |
62 */ | 52 */ |
63 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); | 53 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); |
64 | 54 |
65 /** | 55 /** |
66 * Function prototype for the timer callback function. | 56 * Function prototype for the timer callback function. |
67 */ | |
68 typedef Uint32(SDLCALL * SDL_TimerCallback) (Uint32 interval); | |
69 | |
70 /** | |
71 * Set a callback to run after the specified number of milliseconds has | |
72 * elapsed. The callback function is passed the current timer interval | |
73 * and returns the next timer interval. If the returned value is the | |
74 * same as the one passed in, the periodic alarm continues, otherwise a | |
75 * new alarm is scheduled. If the callback returns 0, the periodic alarm | |
76 * is cancelled. | |
77 * | |
78 * To cancel a currently running timer, call | |
79 * \code SDL_SetTimer(0, NULL); \endcode | |
80 * | |
81 * The timer callback function may run in a different thread than your | |
82 * main code, and so shouldn't call any functions from within itself. | |
83 * | |
84 * The maximum resolution of this timer is 10 ms, which means that if | |
85 * you request a 16 ms timer, your callback will run approximately 20 ms | |
86 * later on an unloaded system. If you wanted to set a flag signaling | |
87 * a frame update at 30 frames per second (every 33 ms), you might set a | |
88 * timer for 30 ms: | |
89 * \code | |
90 * SDL_SetTimer((33/10)*10, flag_update); | |
91 * \endcode | |
92 * | |
93 * If you use this function, you need to pass ::SDL_INIT_TIMER to SDL_Init(). | |
94 * | |
95 * Under UNIX, you should not use raise or use SIGALRM and this function | |
96 * in the same program, as it is implemented using setitimer(). You also | |
97 * should not use this function in multi-threaded applications as signals | |
98 * to multi-threaded apps have undefined behavior in some implementations. | |
99 * | |
100 * \return 0 if successful, or -1 if there was an error. | |
101 */ | |
102 extern DECLSPEC int SDLCALL SDL_SetTimer(Uint32 interval, | |
103 SDL_TimerCallback callback); | |
104 | |
105 /** | |
106 * \name Peter timers | |
107 * New timer API, supports multiple timers | |
108 * Written by Stephane Peter <megastep@lokigames.com> | |
109 */ | |
110 /*@{*/ | |
111 | |
112 /** | |
113 * Function prototype for the new timer callback function. | |
114 * | 57 * |
115 * The callback function is passed the current timer interval and returns | 58 * The callback function is passed the current timer interval and returns |
116 * the next timer interval. If the returned value is the same as the one | 59 * the next timer interval. If the returned value is the same as the one |
117 * passed in, the periodic alarm continues, otherwise a new alarm is | 60 * passed in, the periodic alarm continues, otherwise a new alarm is |
118 * scheduled. If the callback returns 0, the periodic alarm is cancelled. | 61 * scheduled. If the callback returns 0, the periodic alarm is cancelled. |
119 */ | 62 */ |
120 typedef Uint32(SDLCALL * SDL_NewTimerCallback) (Uint32 interval, void *param); | 63 typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param); |
121 | 64 |
122 /** | 65 /** |
123 * Definition of the timer ID type. | 66 * Definition of the timer ID type. |
124 */ | 67 */ |
125 typedef struct _SDL_TimerID *SDL_TimerID; | 68 typedef int SDL_TimerID; |
126 | 69 |
127 /** | 70 /** |
128 * Add a new timer to the pool of timers already running. | 71 * \brief Add a new timer to the pool of timers already running. |
129 * \return A timer ID, or NULL when an error occurs. | 72 * |
73 * \return A timer ID, or NULL when an error occurs. | |
130 */ | 74 */ |
131 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, | 75 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, |
132 SDL_NewTimerCallback | 76 SDL_TimerCallback callback, |
133 callback, void *param); | 77 void *param); |
134 | 78 |
135 /** | 79 /** |
136 * Remove one of the multiple timers knowing its ID. | 80 * \brief Remove a timer knowing its ID. |
137 * \return A boolean value indicating success or failure. | 81 * |
82 * \return A boolean value indicating success or failure. | |
83 * | |
84 * \warning It is not safe to remove a timer multiple times. | |
138 */ | 85 */ |
139 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t); | 86 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID t); |
140 | 87 |
141 /*@}*//*Peter timers*/ | |
142 | 88 |
143 /* Ends C function definitions when using C++ */ | 89 /* Ends C function definitions when using C++ */ |
144 #ifdef __cplusplus | 90 #ifdef __cplusplus |
145 /* *INDENT-OFF* */ | 91 /* *INDENT-OFF* */ |
146 } | 92 } |