coffee/etl
1
0
Fork 0
mirror of https://github.com/ETLCPP/etl.git synced 2026-06-15 08:26:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added callback_timer_deferred_locked documentation

Browse Source
This commit is contained in:
John Wellbelove 2026-05-06 18:31:28 +01:00
parent e1c8a5db11
commit 5bff419ccf
2 changed files with 186 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/timers/callback-timer-atomic.md
View File

@ -50,7 +50,7 @@ etl::timer::id::type register_timer(callback_type callback,
Registers a timer calling a free or static function.
**Parameters**
callback A delegate to the callback funtion that will be callled when the timer expires.
callback A delegate to the callback function that will be called when the timer expires.
period The timer period in ticks.
repeating false if single shot, true if repeating.

264
docs/raw/frameworks/Callback Timer Deferred Locked.txt → docs/timers/callback-timer-deferred-locked.md
View File

@ -1,129 +1,235 @@
Callback Timer Deferred Locked
20.43.0
---
title: "callback_timer_deferred_locked"
---
A software timer class that can manage up to 254 timers. Each one may be repeating or single shot.
When a timer triggers it will call the selected function. The function may be a class member or free function.
The timers are driven from a call to tick(uint32_t count). This call would normally be made from a high priority interrupt routine. The destination function will receive the callback in the same context as the tick call.
The call to tick has a low overhead when a timer is not 'due'. Internally the timers are stored in 'first timeout' order so only the head of the list needs to be checked.
This class is different from the similar etl::callback_timer_locked in that it will record any timer events during the call to tick() so that they may be handled by handle_deferred().
{{< callout type="info">}}
Header: `callback-timer-deferred-locked.h`
Since: `20.43.0`
{{< /callout >}}
Each timer may have a period of up to 232-2 ticks (4,294,967,294).
At 1ms per tick this would equate to just over 49 days.
A software timer class that can manage up to 254 timers. Each one may be repeating or single shot.
When a timer triggers it will call the selected function. The function may be a class member or free function.
The timers are driven from a call to `tick(uint32_t count)`. This call would normally be made from a high priority interrupt routine. The destination function will receive the callback in the same context as the tick call.
The call to tick has a low overhead when a timer is not 'due'. Internally the timers are stored in 'first timeout' order so only the head of the list needs to be checked.
This class is different from the similar `etl::callback_timer_locked` in that it will record any timer events during the call to `tick()` so that they may be handled by `handle_deferred()`.
Defines the following classes:-
Each timer may have a period of up to 2<sup>32</sup>-2 ticks (4,294,967,294).
At 1ms per tick this would equate to just over 49 days.
**Defines the following classes**
```cpp
etl::icallback_timer_locked
etl::callback_timer_deferred_locked
```
The access to the timers is controlled by three external functions, supplied to the timer by the
member function set_locks.
The access to the timers is controlled by three external functions, supplied to the timer by the member function set_locks.
The three delegate parameters are:-
Try Lock Attempts to set the lock. Returns true if successful, otherwise false.
Lock Sets the lock.
Unlock Resets the lock.
Uses definitions from `timer.h`.
Uses definitions from timer.h
**Important**
For correct operation of the timer framework, the routine that calls tick must not be pre-emptible by another routine that calls a timer function. Also, calls to the timer framework may only be made from the caller of tick and one other, lower priority, thread of execution.
Important:
For correct operation of the timer framework, the routine that calls tick must not be pre-emptible by another routine that calls a timer function. Also, calls to the timer framework may only be made from the caller of tick and one other, lower priority, thread of execution
____________________________________________________________________________________________________
icallback_timer_locked
The base class for all timer controllers.
---
Type definitions
## icallback_timer_locked
The base class for all timer controllers.
### Type definitions
```cpp
callback_type etl::delegate<void(void)>
```
The function type used for callbacks.
```cpp
try_lock_type etl::delegate<bool(void)>
```
The function type used for 'try lock'.
```cpp
lock_type etl::delegate<void(void)>
```
The function type used for 'lock'.
```cpp
unlock_type etl::delegate<void(void)>
```
The function type used for 'unlock'.
____________________________________________________________________________________________________
Member functions
### Member functions
```cpp
etl::timer::id::type register_timer(callback_type callback),
uint32_t period,
bool repeating)
```
**Description**
Registers a timer calling a free or static function.
callback A delegate to the callback free funtion that will be callled when the timer expires.
period The timer period in ticks.
repeating false if single shot, true if repeating.
Returns the allocated timer id or etl::timer::mode::NO_TIMER if one was not available.
____________________________________________________________________________________________________
**Parameters**
`callback` A delegate to the callback free function that will be called when the timer expires.
`period` The timer period in ticks.
`repeating` `false` if single shot, `true` if repeating.
**Return**
The allocated timer id or `etl::timer::mode::NO_TIMER` if one was not available.
---
```cpp
bool unregister_timer(etl::timer::id::type id)
Unregisters a timer.
If the timer is active then it will be stopped.
Returns true if a timer with the id was successfully unregistered.
___________________________________________________________________________________________________
```
**Description**
Unregisters a timer.
If the timer is active then it will be stopped.
**Return**
`true` if a timer with the id was successfully unregistered.
---
```cpp
void enable(bool state)
```
**Description**
Enables or disables the timer manager according to the state.
____________________________________________________________________________________________________
---
```cpp
bool is_running() const
Returns true if the timer manager is enabled.
____________________________________________________________________________________________________
```
**Description**
Returns `true` if the timer manager is enabled.
---
```cpp
void clear()
```
**Description**
Clears the callback timer back to the initial state. All timers will be stopped and unregistered.
____________________________________________________________________________________________________
---
```cpp
bool tick(uint32_t count)
This function updates the internal tick counter (if enabled) and must pass the number of ticks that have occurred since the last call. If the count encompasses more than one period of a repeating timer then the timer will be triggered multiple times in one call to tick.
Returns true if the tick counter was updated, otherwise false. This may be used by the calling routine to accumulate unprocessed tick counts.
Any triggered events will be recorded so that they
____________________________________________________________________________________________________
```
**Description**
This function updates the internal tick counter (if enabled) and must pass the number of ticks that have occurred since the last call. If the count encompasses more than one period of a repeating timer then the timer will be triggered multiple times in one call to tick.
**Return**
`true` if the tick counter was updated, otherwise `false`. This may be used by the calling routine to accumulate unprocessed tick counts.
Any triggered events will be recorded so that they can be deferred.
---
```cpp
void handle_deferred()
Handles the work collected during the tick() call.
You can call this function after tick() or you can call this on another task to handle the timer events.
____________________________________________________________________________________________________
```
**Description**
Handles the work collected during the `tick()` call.
You can call this function after `tick()` or you can call this on another task to handle the timer events.
---
```cpp
bool start(etl::timer::id::type id, bool immediate = false)
Starts the timer with the specified id.
If the timer is already running then the timer Is restarted from the current tick count.
If immediate is true then the timer is triggered on the next call to tick(). Note: Single shot timers will only trigger once.
If the id does not correspond to a registered timer then returns false.
____________________________________________________________________________________________________
```
**Description**
Starts the timer with the specified id.
If the timer is already running then the timer Is restarted from the current tick count.
If immediate is true then the timer is triggered on the next call to tick(). Note: Single shot timers will only trigger once.
If the id does not correspond to a registered timer then returns `false`.
---
```cpp
bool stop(etl::timer::id::type id)
Stops the timer with the specified id.
Does nothing if the timer is already stopped.
if the id does not correspond to a registered timer then returns false.
____________________________________________________________________________________________________
```
**Description**
Stops the timer with the specified id.
Does nothing if the timer is already stopped.
If the id does not correspond to a registered timer then returns `false`.
---
```cpp
bool set_period(etl::timer::id::type id, uint32_t period)
Stops the timer with the specified id.
Sets a new timer period.
Returns true if successful.
____________________________________________________________________________________________________
```
**Description**
Stops the timer with the specified id.
Sets a new timer period.
**Return**
`true` if successful.
---
```cpp
bool set_mode(etl::timer::id::type id, bool repeating)
Stops the timer with the specified id.
Sets a new timer mode.
Returns true if successful.
____________________________________________________________________________________________________
```
**Description**
Stops the timer with the specified id.
Sets a new timer mode.
**Return**
`true` if successful.
---
```cpp
void set_locks(try_lock_type try_lock_, lock_type lock_, lock_type unlock_)
```
**Description**
Sets the try-lock, lock and unlock delegates.
____________________________________________________________________________________________________
---
```cpp
etl::timer::id::type time_to_next()
```
**Description**
Returns the time to the next timeout.
20.38.0
____________________________________________________________________________________________________
Constants
MAX_TIMERS
Since: `20.38.0`
### Constants
`Max_Timers`
The maximum number of timers that can be handled.
____________________________________________________________________________________________________
callback_timer_locked
Template parameters
MAX_TIMERS The number of timers to be supported. The maximum number is 254.
A value of 255 will result in a compile error.
---
## callback_timer_locked
```cpp
template <uint_least8_t Max_Timers, uint32_t Max_Handlers>
class callback_timer_deferred_locked
```
**Template parameters**
`Max_Timers` The number of timers to be supported. The maximum number is 254.
A value of 255 will result in a compile error.
`Max_Handlers`
The max number of deferred timer events.
---
```cpp
callback_timer_locked()
Default construct.
```
**Description**
Default construct.
The lock callback delegates are not set.
____________________________________________________________________________________________________
callback_timer_locked(try_lock_type try_lock, lock_type lock, unlock_type unlock)
Construct from lock callback delegates.
____________________________________________________________________________________________________
Example
---
```cpp
callback_timer_locked(try_lock_type try_lock, lock_type lock, unlock_type unlock)
```
**Description**
Construct from lock callback delegates.
## Example
```cpp
//***************************************************************************
// Class callback via etl::function
//***************************************************************************
@ -211,4 +317,4 @@ void timer_interrupt()
nticks += TICK;
}
}
```