modm API documentation
|
Classes | |
class | modm::GenericPeriodicTimer< Clock, Duration > |
enum | modm::TimerState : uint8_t { Stopped = 0b001, Expired = 0b010, Armed = 0b100 } |
Possible states of a timeout. | |
using | modm::ShortTimeout = GenericTimeout< Clock, ShortDuration > |
using | modm::Timeout = GenericTimeout< Clock, Duration > |
Software timeout for up to 49 days with millisecond resolution. | |
using | modm::ShortPreciseTimeout = GenericTimeout< PreciseClock, ShortPreciseDuration > |
Software timeout for up to 65 milliseconds with microsecond resolution. | |
using | modm::PreciseTimeout = GenericTimeout< PreciseClock, PreciseDuration > |
Software timeout for up to 71 minutes with microsecond resolution. | |
using | modm::ShortDuration = std::chrono::duration< uint16_t, std::milli > |
16bit duration, which can hold up to 65 seconds at millisecond resolution. | |
using | modm::Duration = std::chrono::duration< uint32_t, std::milli > |
32bit duration, which can hold up to 49 days at millisecond resolution. | |
using | modm::ShortPreciseDuration = std::chrono::duration< uint16_t, std::micro > |
16bit precise duration, which can hold up to 65 milliseconds at microsecond resolution. | |
using | modm::PreciseDuration = std::chrono::duration< uint32_t, std::micro > |
32bit precise duration, which can hold up to 71 minutes at microsecond resolution. | |
using | modm::ShortTimestamp = std::chrono::time_point< modm::chrono::milli_clock, ShortDuration > |
16bit time point, which can hold up to 65 seconds at millisecond resolution. | |
using | modm::Timestamp = modm::chrono::milli_clock::time_point |
32bit time point, which can hold up to 49 days at millisecond resolution. | |
using | modm::ShortPreciseTimestamp = std::chrono::time_point< modm::chrono::micro_clock, ShortPreciseDuration > |
16bit precise time point, which can hold up to 65 milliseconds at microsecond resolution. | |
using | modm::PreciseTimestamp = modm::chrono::micro_clock::time_point |
32bit precise time point, which can hold up to 71 minutes at microsecond resolution. | |
lbuild module: modm:processing:timer
This module provides polling based software timers for executing code after a delay or periodically in millisecond resolution via modm::Clock
and in microsecond resolution via modm::PreciseClock
.
To delay or delegate execution to the future, you can use modm::Timeout
to set a duration after which the timeout expires and executes your code:
However, this construct is not very useful, particularly since you could also simply use modm::delay(100ms)
for this, so instead use the execute()
method to poll non-blockingly for expiration:
The execute()
method returns true only once after expiration, so it can be continuously polled somewhere in your code. A more comfortable use-case is to use a modm::Timeout
inside a class that needs to provide some asynchronous method for timekeeping:
However, for more complex use-cases, these classes are intended to be used with Protothreads (from module modm:processing:protothread
) or Resumable Functions (from module modm:processing:resumable
) to implement non-blocking delays.
For periodic timeouts, you could simply restart the timeout, however, the restart()
method schedules a timeout from the current time onwards:
This can lead to longer period than required, particularly in a system that has a lot to do and cannot service every timeout immediately. The solution is to use a modm::PeriodicTimer
, which only reimplements the execute()
method to automatically restart the timer, by adding the interval to the old time, thus keeping the period accurate:
The execute()
method actually returns the number of missed periods, so that in a heavily congested system you do not need to keep track of time yourself. This can be particularly useful when dealing with soft-time physical systems like LED animations or control loops:
execute()
methods as often as required. If you need to meet hard real time deadlines these are not the timers you are looking for!Two timer resolutions are available, using modm::Clock
for milliseconds and modm::PreciseClock
for microseconds. They follow the same naming scheme:
modm::Timeout
, modm::PeriodicTimer
: 49 days in milliseconds and 8 bytes.modm::PreciseTimeout
, modm::PrecisePeriodicTimer
: 71 mins in microseconds and 8 bytes.If you deal with short time periods, you can save a little memory by using the 16-bit versions of the same timers:
modm::ShortTimeout
, modm::ShortPeriodicTimer
: 65 seconds in milliseconds and 4 bytes.modm::ShortPreciseTimeout
, modm::ShortPrecisePeriodicTimer
: 65 milliseconds in microseconds and 4 bytes. using modm::ShortTimeout = typedef GenericTimeout< Clock, ShortDuration > |
Software timeout for up to 65 seconds with millisecond resolution.
Extra care must be taken when not calling the isExpired() method for more than 65 seconds. Due to an overflow in the implementation this might add an additional delay of up to 65s ticks in the worst case. Always call restart() before reusing the timer to avoid this behaviour.
If you need a longer time period, use Timeout.