simple timerpool implementation for uncritical event-purposes. The "tick" is an abstract value and depends on the selected timebase and the environment
166 |Its useful if you need wakeup-timers for protocol implementations or you like to calculate/interpolate something for a given timeslot
167 |For each TimerPool object only one tickthread is spawned which handles the message-queue and the lifecycle of the TimerHandle. The maximum amount of timers is only constrained by memory and the given timebase.
168 |The allocation of a new TimerHandle always block but is threadsafe. The maximum blocking-time relates directly to your given timebase of the pool
169 |There is a blocking and a nonblocking API on the TimerHandles which can be used simulataneously from different threads at once. All actions on the TimerHandles are completely threadsafe and the ptrs itself can be shared between threads.
170 |the following example demonstrates the basic use. For detailed api use and for multithreading examples use the tests as a starter.
171 |import timerpool 172 | 173 | let 174 | tpRef = timerpool.newTimerPool(10.int) # timerpool with 10ms timebase 175 | timerhdl = allocTimer(tpRef) 176 | 177 | timerhdl.setAlarmCounter(5) # set expiration to 50ms (timebase * 5) 178 | 179 | while timerhdl.getAlarmCounter() > 0: # you can poll it 180 | discard 181 | 182 | timerhdl.waitForAlarm() # or sleep till timer expired 183 | timerhdl.deallocTimer() # pushes the timer back to pool 184 | tpRef.shutdownTimerPool() # shutdown the pool and blocks till all 185 | # timers are expired186 |
Types
188 |-
189 |
190 |
TimerHandlePtr = ptr TimerHandle
191 | - 192 | 193 | pointer type to the timerpoolhandle. 194 | 195 | 196 | 197 |
TPError = object of Exception 198 |
199 | - 200 | 201 | generic exception 202 | 203 | 204 | 205 |
TimerPoolPtr = ptr TimerPool
206 | - 207 | 208 | used to share among threads 209 | 210 | 211 | 212 |
TimerPoolRef = ref TimerPool
213 | - 214 | 215 | 216 | 217 | 218 | 219 |
Tickval = range[1 .. int.high]
220 | - 221 | 222 | 223 | 224 | 225 | 226 |
MinTimerval = range[1 .. int.high]
227 | - 228 | 229 | integer type used to initialise the timerpool and to set the timeout of the timer 230 | 231 | 232 | 233 |
PoolStats = tuple[runningCount: int, freedCount: int, inactiveCount: int]
234 | - 235 | 236 | container type returned by waitForGetStats. the sum of runningCount,freedCount and inactiveCount is the total amount of timerhandles within the pool 237 | 238 | 239 | 240 |
Procs
243 |-
244 |
245 |
proc initThreadContext(tpptr: TimerPoolPtr): void {...}{.raises: [TPError], tags: [].}
246 | -
247 |
248 |
to be called explicit if the pool-accessing thread is not the owner of the timerpool (initialises threadvar globs)
249 |raises a TPError if called within the spawning thread
250 | 251 | 252 |
253 |
254 | proc newTimerPool(tbase_ms: Tickval = 100; minFreedTimers: MinTimerval = 5): ref TimerPool {...}{. 255 | raises: [], tags: [].}
256 | - 257 | 258 | creator proc. The tickval is of milliseconds and the default timebase is 100 milliseconds the default of the mintimers parameter is 5 (shrink_pool leave this minimum amount of freed timers within the pool) 259 | 260 | 261 | 262 |
proc deinitThreadContext(tpptr: TimerPoolPtr): void {...}{.raises: [TPError], tags: [].}
263 | -
264 |
265 |
call this proc if the pool-accessing thread should be detached from the timerpool (cleanup threadvar globs)
266 |call this proc only if the current thread is not owner of the timerpool. if not a TPError is raised
267 | 268 | 269 |
270 |
271 | proc allocTimer(tpptr: TimerPoolPtr): TimerHandlePtr {...}{.raises: [TPError], tags: [].}
272 | -
273 |
274 |
returns a timerhandle. the timer is always of type:oneshot but could also act as a continous one. in this case the caller needs to reset the alarm to the needed value. This threadsafe call blocks till the request was handled by the pool-tick-thread
275 |before calling (if the pool was not spawned by the calling thread) initThreadContext() should be called
276 |raises TPError if the pointer parameter is nil and/or the threadContext was not initialised with initThreadContext
277 | 278 | 279 |
280 |
281 | proc allocTimer(tpptr: TimerPoolRef): TimerHandlePtr {...}{.inline, raises: [TPError], 282 | tags: [].}
283 | - 284 | 285 | 286 | 287 | 288 | 289 |
proc deallocTimer(timerhdl: TimerHandlePtr): void {...}{.raises: [TPError], tags: [].}
290 | -
291 |
292 |
the timer handle is pushed back to the pool. once freed it is not handled by the timerscan any more and its recycled for later use
293 |this proc could be called from multiple threads simultaneously. if one ore more threads are waiting on the timers signal all threads gets informed. This call is part of the nonblocking api
294 |raises TPError if the pointer parameter is nil
295 | 296 | 297 |
298 |
299 | proc setAlarmCounter(timerhdl: TimerHandlePtr; value: Tickval): void {...}{. 300 | raises: [TPError], tags: [].}
301 | -
302 |
303 |
sets the timers countdown alarm-value to the given one. reset the counter after it´s fired to obtain a continous timer
304 |this call is threadsafe and part of the nonblocking-api
305 |raises TPError if the pointer parameter is nil or the timer is freed
306 | 307 | 308 |
309 |
310 | proc getAlarmCounter(timerhdl: TimerHandlePtr): int {...}{.raises: [TPError], tags: [].}
311 | -
312 |
313 |
returns the current value of the alarmcounter could be used for a polling-style-waiting_for_timer_fired
314 |this call is threadsafe and part of the nonblocking-api
315 |raises TPError if the pointer parameter is nil or the timer already freed
316 | 317 | 318 |
319 |
320 | proc waitForAlarm(timerhdl: TimerHandlePtr): void {...}{.raises: [TPError], tags: [].}
321 | -
322 |
323 |
blocking wait till the alarmcounter is decremented to 0
324 |threadsafe impl and could be called by multiple threads simultaniously
325 |raises TPError if the pointer parameter is nil or the timer already freed
326 | 327 | 328 |
329 |
330 | proc waitForGetStats(tpptr: TimerPoolPtr): PoolStats {...}{.raises: [TPError], tags: [].}
331 | -
332 |
333 |
fetches some pool statistics for debugging purposes
334 |raises TPError if the pointer parameter is nil or the threadContext was not initialized with initThreadContext
335 | 336 | 337 |
338 |
339 | proc shrinkTimerPool(tpptr: TimerPoolPtr) {...}{.raises: [TPError], tags: [].}
340 | -
341 |
342 |
shrinks the pool of freed Timers. the given minFreedTimers value at pool construction specifies the lower watermark
343 |this is a nonblocking call. raises TPError if the pointer parameter is nil and/or the threadContext was not initialised with initThreadContext (only needed if the pool was not spawned by the caller)
344 | 345 | 346 |
347 |
348 |
Templates
351 |-
352 |
353 |
template checkForNil(timerhdl: TimerHandlePtr; callingProc: string = ""): void
354 | - 355 | 356 | checks if the timerhdl is nil. if so a TPError is raised 357 | 358 | 359 | 360 |
template poolRef2Ptr(stpp: TimerPoolRef): TimerPoolPtr
361 | - 362 | 363 | convenience template to get the TimerPoolPtr from the ref 364 | 365 | 366 | 367 |