sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Timer

Description

SDL provides time management functionality. It is useful for dealing with (usually) small durations of time.

This is not to be confused with calendar time management, which is provided by CategoryTime.

This category covers measuring time elapsed (getTicks, getPerformanceCounter), putting a thread to sleep for a certain amount of time (delay, delayNS, delayPrecise), and firing a callback function after a certain amount of time has elapsed (addTimer, etc).

There are also useful macros to convert between time units, like secondsToNs and such. Number of milliseconds in a second.

This is always 1000.

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Timer.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

The C shims are functions this package defines in C over what the FFI cannot call directly (variadic functions, function-like macros), each named after what it wraps; the same flavor rules apply. Their raw imports live under SDL3.Sys.Bindgen.TimerShims.

Full conventions: SDL3.Sys.

Since: 3.2.0

Synopsis

Documentation

module SDL3.Sys.Bindgen.Timer

Function aliases

getTicks :: IO Word64 Source #

Get the number of milliseconds that have elapsed since the SDL library initialization.

Returns
an unsigned 64‑bit integer that represents the number of milliseconds that have elapsed since the SDL library was initialized (typically via a call to SDL_Init).
Thread safety
It is safe to call this function from any thread.
See also
getTicksNS

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetTicks. The safe import is not exported : reads a monotonic clock value; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetTicks, defined at SDL3/SDL_timer.h 201:36

Since: 3.2.0

getTicksNS :: IO Word64 Source #

Get the number of nanoseconds since SDL library initialization.

Returns
an unsigned 64-bit value representing the number of nanoseconds since the SDL library initialized.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetTicksNS. The safe import is not exported : reads a monotonic clock value; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetTicksNS, defined at SDL3/SDL_timer.h 213:36

Since: 3.2.0

getPerformanceCounter :: IO Word64 Source #

Get the current value of the high resolution counter.

This function is typically used for profiling.

The counter values are only meaningful relative to each other. Differences between values can be converted to times by using getPerformanceFrequency.

Returns
the current counter value.
Thread safety
It is safe to call this function from any thread.
See also
getPerformanceFrequency

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetPerformanceCounter. The safe import is not exported : reads a monotonic clock value; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetPerformanceCounter, defined at SDL3/SDL_timer.h 232:36

Since: 3.2.0

getPerformanceFrequency :: IO Word64 Source #

Get the count per second of the high resolution counter.

Returns
a platform-specific count per second.
Thread safety
It is safe to call this function from any thread.
See also
getPerformanceCounter

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetPerformanceFrequency. The safe import is not exported : reads a monotonic clock value; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetPerformanceFrequency, defined at SDL3/SDL_timer.h 245:36

Since: 3.2.0

delay Source #

Arguments

:: Word32
ms
the number of milliseconds to delay.
-> IO () 

Wait a specified number of milliseconds before returning.

This function waits a specified number of milliseconds before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Thread safety
It is safe to call this function from any thread.
See also
delayNS, delayPrecise

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_Delay. The safe flavor is delaySafe : sleeps the OS thread; an unsafe call stalls every capability and GC for the duration.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_Delay, defined at SDL3/SDL_timer.h 263:34

Since: 3.2.0

delaySafe Source #

Arguments

:: Word32
ms
the number of milliseconds to delay.
-> IO () 

Wait a specified number of milliseconds before returning.

This function waits a specified number of milliseconds before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Thread safety
It is safe to call this function from any thread.
See also
delayNS, delayPrecise

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_Delay. The unsafe flavor is delay : sleeps the OS thread; an unsafe call stalls every capability and GC for the duration.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_Delay, defined at SDL3/SDL_timer.h 263:34

Since: 3.2.0

delayNS Source #

Arguments

:: Word64
ns
the number of nanoseconds to delay.
-> IO () 

Wait a specified number of nanoseconds before returning.

This function waits a specified number of nanoseconds before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Thread safety
It is safe to call this function from any thread.
See also
delay, delayPrecise

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_DelayNS. The safe flavor is delayNSSafe : sleeps the OS thread; an unsafe call stalls every capability and GC for the duration.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_DelayNS, defined at SDL3/SDL_timer.h 281:34

Since: 3.2.0

delayNSSafe Source #

Arguments

:: Word64
ns
the number of nanoseconds to delay.
-> IO () 

Wait a specified number of nanoseconds before returning.

This function waits a specified number of nanoseconds before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Thread safety
It is safe to call this function from any thread.
See also
delay, delayPrecise

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_DelayNS. The unsafe flavor is delayNS : sleeps the OS thread; an unsafe call stalls every capability and GC for the duration.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_DelayNS, defined at SDL3/SDL_timer.h 281:34

Since: 3.2.0

delayPrecise Source #

Arguments

:: Word64
ns
the number of nanoseconds to delay.
-> IO () 

Wait a specified number of nanoseconds before returning.

This function waits a specified number of nanoseconds before returning. It will attempt to wait as close to the requested time as possible, busy waiting if necessary, but could return later due to OS scheduling.

Thread safety
It is safe to call this function from any thread.
See also
delay, delayNS

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_DelayPrecise. The safe flavor is delayPreciseSafe : sleeps the OS thread; an unsafe call stalls every capability and GC for the duration.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_DelayPrecise, defined at SDL3/SDL_timer.h 299:34

Since: 3.2.0

delayPreciseSafe Source #

Arguments

:: Word64
ns
the number of nanoseconds to delay.
-> IO () 

Wait a specified number of nanoseconds before returning.

This function waits a specified number of nanoseconds before returning. It will attempt to wait as close to the requested time as possible, busy waiting if necessary, but could return later due to OS scheduling.

Thread safety
It is safe to call this function from any thread.
See also
delay, delayNS

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_DelayPrecise. The unsafe flavor is delayPrecise : sleeps the OS thread; an unsafe call stalls every capability and GC for the duration.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_DelayPrecise, defined at SDL3/SDL_timer.h 299:34

Since: 3.2.0

addTimer Source #

Arguments

:: Word32
interval
the timer delay, in milliseconds, passed to callback.
-> SDL_TimerCallback
callback
the SDL_TimerCallback function to call when the specified interval elapses.
-> Ptr Void
userdata
a pointer that is passed to callback.
-> IO SDL_TimerID 

Call a callback function at a future time.

The callback function is passed the current timer interval and the user supplied parameter from the addTimer call and should return the next timer interval. If the value returned from the callback is 0, the timer is canceled and will be removed.

The callback is run on a separate thread, and for short timeouts can potentially be called before this function returns.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ms to execute and returned 1000 (ms), the timer would only wait another 750 ms before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with getTicksNS or getPerformanceCounter in case your callback needs to adjust for variances.

Returns
a timer ID or 0 on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
addTimerNS, removeTimer

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_AddTimer. The safe flavor is addTimerSafe : registration; the timer fires on SDL's timer thread.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_AddTimer, defined at SDL3/SDL_timer.h 368:41

Since: 3.2.0

addTimerSafe Source #

Arguments

:: Word32
interval
the timer delay, in milliseconds, passed to callback.
-> SDL_TimerCallback
callback
the SDL_TimerCallback function to call when the specified interval elapses.
-> Ptr Void
userdata
a pointer that is passed to callback.
-> IO SDL_TimerID 

Call a callback function at a future time.

The callback function is passed the current timer interval and the user supplied parameter from the addTimer call and should return the next timer interval. If the value returned from the callback is 0, the timer is canceled and will be removed.

The callback is run on a separate thread, and for short timeouts can potentially be called before this function returns.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ms to execute and returned 1000 (ms), the timer would only wait another 750 ms before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with getTicksNS or getPerformanceCounter in case your callback needs to adjust for variances.

Returns
a timer ID or 0 on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
addTimerNS, removeTimer

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_AddTimer. The unsafe flavor is addTimer : registration; the timer fires on SDL's timer thread.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_AddTimer, defined at SDL3/SDL_timer.h 368:41

Since: 3.2.0

addTimerNS Source #

Arguments

:: Word64
interval
the timer delay, in nanoseconds, passed to callback.
-> SDL_NSTimerCallback
callback
the SDL_TimerCallback function to call when the specified interval elapses.
-> Ptr Void
userdata
a pointer that is passed to callback.
-> IO SDL_TimerID 

Call a callback function at a future time.

The callback function is passed the current timer interval and the user supplied parameter from the addTimerNS call and should return the next timer interval. If the value returned from the callback is 0, the timer is canceled and will be removed.

The callback is run on a separate thread, and for short timeouts can potentially be called before this function returns.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ns to execute and returned 1000 (ns), the timer would only wait another 750 ns before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with getTicksNS or getPerformanceCounter in case your callback needs to adjust for variances.

Returns
a timer ID or 0 on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
addTimer, removeTimer

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_AddTimerNS. The safe flavor is addTimerNSSafe : registration; the timer fires on SDL's timer thread.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_AddTimerNS, defined at SDL3/SDL_timer.h 430:41

Since: 3.2.0

addTimerNSSafe Source #

Arguments

:: Word64
interval
the timer delay, in nanoseconds, passed to callback.
-> SDL_NSTimerCallback
callback
the SDL_TimerCallback function to call when the specified interval elapses.
-> Ptr Void
userdata
a pointer that is passed to callback.
-> IO SDL_TimerID 

Call a callback function at a future time.

The callback function is passed the current timer interval and the user supplied parameter from the addTimerNS call and should return the next timer interval. If the value returned from the callback is 0, the timer is canceled and will be removed.

The callback is run on a separate thread, and for short timeouts can potentially be called before this function returns.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ns to execute and returned 1000 (ns), the timer would only wait another 750 ns before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with getTicksNS or getPerformanceCounter in case your callback needs to adjust for variances.

Returns
a timer ID or 0 on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
addTimer, removeTimer

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_AddTimerNS. The unsafe flavor is addTimerNS : registration; the timer fires on SDL's timer thread.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_AddTimerNS, defined at SDL3/SDL_timer.h 430:41

Since: 3.2.0

removeTimer Source #

Arguments

:: SDL_TimerID
id
the ID of the timer to remove.
-> IO Bool 

Remove a timer created with addTimer.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
addTimer

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_RemoveTimer. The safe flavor is removeTimerSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_RemoveTimer, defined at SDL3/SDL_timer.h 445:34

Since: 3.2.0

removeTimerSafe Source #

Arguments

:: SDL_TimerID
id
the ID of the timer to remove.
-> IO Bool 

Remove a timer created with addTimer.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
addTimer

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_RemoveTimer. The unsafe flavor is removeTimer .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_RemoveTimer, defined at SDL3/SDL_timer.h 445:34

Since: 3.2.0

C shims

secondsToNs Source #

Arguments

:: Word64
s
the number of seconds to convert.
-> IO Word64 

Convert seconds to nanoseconds.

The SDL_SECONDS_TO_NS macro as a function. This only converts whole numbers, not fractional seconds.

Returns
s, expressed in nanoseconds.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of lithon_SDL_SECONDS_TO_NS. The safe import is not exported : pure math on immediate values; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
lithon_SDL_SECONDS_TO_NS, defined at sdl3-bindgen-sys/SDL_timer_shims.h 37:26

Since: 3.2.0

msToNs Source #

Arguments

:: Word64
ms
the number of milliseconds to convert.
-> IO Word64 

Convert milliseconds to nanoseconds.

The SDL_MS_TO_NS macro as a function. This only converts whole numbers, not fractional milliseconds.

Returns
ms, expressed in nanoseconds.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of lithon_SDL_MS_TO_NS. The safe import is not exported : pure math on immediate values; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
lithon_SDL_MS_TO_NS, defined at sdl3-bindgen-sys/SDL_timer_shims.h 55:26

Since: 3.2.0

usToNs Source #

Arguments

:: Word64
us
the number of microseconds to convert.
-> IO Word64 

Convert microseconds to nanoseconds.

The SDL_US_TO_NS macro as a function. This only converts whole numbers, not fractional microseconds.

Returns
us, expressed in nanoseconds.
Thread safety
It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of lithon_SDL_US_TO_NS. The safe import is not exported : pure math on immediate values; cannot block, lock, or call back.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
lithon_SDL_US_TO_NS, defined at sdl3-bindgen-sys/SDL_timer_shims.h 73:26

Since: 3.2.0