Struct Timer 

pub struct Timer {
    pub handle: TimerHandle,
    /* private fields */
}

Software timer types for periodic and one-shot callbacks. A software timer that executes a callback at regular intervals.

Timers can be configured as:

• One-shot: Executes once after the specified period
• Auto-reload: Executes repeatedly at the specified interval

Timer callbacks execute in the context of the timer daemon task, not in interrupt context. This means they can call most RTOS functions safely.

Important Notes

• Timer callbacks should complete quickly to avoid delaying other timers
• Callbacks must not block indefinitely
• Requires configUSE_TIMERS = 1 in FreeRTOSConfig.h

Examples

One-shot timer

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
let timer = Timer::new_with_to_tick(
    "oneshot",
    Duration::from_secs(1),
    false,  // Not auto-reload (one-shot)
    None,
    |timer, param| {
        println!("Timer fired once!");
        Ok(param)
    }
).unwrap();
 
timer.start_with_to_tick(Duration::from_millis(10)).unwrap();

Periodic timer

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
let timer = Timer::new_with_to_tick(
    "periodic",
    Duration::from_millis(500),
    true,  // Auto-reload (periodic)
    None,
    |timer, param| {
        println!("Tick every 500ms");
        Ok(param)
    }
).unwrap();
 
timer.start_with_to_tick(Duration::from_millis(10)).unwrap();
 
// Stop after some time
Duration::from_secs(5).sleep();
timer.stop_with_to_tick(Duration::from_millis(10));

Timer with custom parameters

use osal_rs::os::{Timer, TimerFn, TimerParam};
use alloc::sync::Arc;
use core::time::Duration;
 
struct CounterData {
    count: u32,
}
 
let data = Arc::new(CounterData { count: 0 });
let param: TimerParam = data.clone();
 
let timer = Timer::new_with_to_tick(
    "counter",
    Duration::from_secs(1),
    true,
    Some(param),
    |timer, param| {
        if let Some(param_arc) = param {
            if let Some(data) = param_arc.downcast_ref::<CounterData>() {
                println!("Counter: {}", data.count);
            }
        }
        Ok(None)
    }
).unwrap();
 
timer.start_with_to_tick(Duration::from_millis(10));

Changing timer period

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
let timer = Timer::new_with_to_tick(
    "adjustable",
    Duration::from_millis(100),
    true,
    None,
    |_, _| { println!("Tick"); Ok(None) }
).unwrap();
 
timer.start_with_to_tick(Duration::from_millis(10));
 
// Change period to 500ms
Duration::from_secs(2).sleep();
timer.change_period_with_to_tick(
    Duration::from_millis(500),
    Duration::from_millis(10)
);

Resetting a timer

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
let timer = Timer::new_with_to_tick(
    "watchdog",
    Duration::from_secs(5),
    false,
    None,
    |_, _| { println!("Timeout!"); Ok(None) }
).unwrap();
 
timer.start_with_to_tick(Duration::from_millis(10));
 
// Reset timer before it expires (like a watchdog)
Duration::from_secs(2).sleep();
timer.reset_with_to_tick(Duration::from_millis(10));  // Restart the 5s countdown

Fields

handle: TimerHandle

FreeRTOS timer handle

Implementations

impl Timer

pub fn new_with_to_tick<F>( name: &str, timer_period_in_ticks: impl ToTick, auto_reload: bool, param: Option<TimerParam>, callback: F, ) -> Result<Self>

where F: Fn(Box<dyn TimerFn>, Option<TimerParam>) -> Result<TimerParam> + Send + Sync + Clone + 'static,

Creates a new software timer with tick conversion.

This is a convenience method that accepts any type implementing ToTick (like Duration) for the timer period.

Parameters

• name - Timer name for debugging
• timer_period_in_ticks - Timer period (e.g., Duration::from_secs(1))
• auto_reload - true for periodic, false for one-shot
• param - Optional parameter passed to callback
• callback - Function called when timer expires

Returns

• Ok(Self) - Successfully created timer
• Err(Error) - Creation failed

Examples

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
let timer = Timer::new_with_to_tick(
    "periodic",
    Duration::from_secs(1),
    true,
    None,
    |_timer, _param| { println!("Tick"); Ok(None) }
).unwrap();

pub fn start_with_to_tick(&self, ticks_to_wait: impl ToTick) -> OsalRsBool

Starts the timer with tick conversion.

Convenience method that accepts any type implementing ToTick.

Parameters

• ticks_to_wait - Maximum time to wait for the command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer started successfully
• OsalRsBool::False - Failed to start timer

Examples

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
timer.start_with_to_tick(Duration::from_millis(10));

pub fn stop_with_to_tick(&self, ticks_to_wait: impl ToTick) -> OsalRsBool

Stops the timer with tick conversion.

Convenience method that accepts any type implementing ToTick.

Parameters

• ticks_to_wait - Maximum time to wait for the command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer stopped successfully
• OsalRsBool::False - Failed to stop timer

Examples

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
timer.stop_with_to_tick(Duration::from_millis(10));

pub fn reset_with_to_tick(&self, ticks_to_wait: impl ToTick) -> OsalRsBool

Resets the timer with tick conversion.

Resets the timer to restart its period. For one-shot timers, this restarts them. For periodic timers, this resets the period.

Parameters

• ticks_to_wait - Maximum time to wait for the command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer reset successfully
• OsalRsBool::False - Failed to reset timer

Examples

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
// Reset watchdog timer before it expires
timer.reset_with_to_tick(Duration::from_millis(10));

pub fn change_period_with_to_tick( &self, new_period_in_ticks: impl ToTick, new_period_ticks: impl ToTick, ) -> OsalRsBool

Changes the timer period with tick conversion.

Convenience method that accepts any type implementing ToTick.

Parameters

• new_period_in_ticks - New timer period
• new_period_ticks - Maximum time to wait for the command to be sent to timer daemon

Returns

• OsalRsBool::True - Period changed successfully
• OsalRsBool::False - Failed to change period

Examples

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
// Change from 1 second to 500ms
timer.change_period_with_to_tick(
    Duration::from_millis(500),
    Duration::from_millis(10)
);

pub fn delete_with_to_tick(&mut self, ticks_to_wait: impl ToTick) -> OsalRsBool

Deletes the timer with tick conversion.

Convenience method that accepts any type implementing ToTick.

Parameters

• ticks_to_wait - Maximum time to wait for the command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer deleted successfully
• OsalRsBool::False - Failed to delete timer

Examples

use osal_rs::os::{Timer, TimerFn};
use core::time::Duration;
 
timer.delete_with_to_tick(Duration::from_millis(10));

impl Timer

pub fn new<F>( name: &str, timer_period_in_ticks: TickType, auto_reload: bool, param: Option<TimerParam>, callback: F, ) -> Result<Self>

where F: Fn(Box<dyn TimerFn>, Option<TimerParam>) -> Result<TimerParam> + Send + Sync + Clone + 'static,

Creates a new software timer.

Parameters

• name - Timer name for debugging
• timer_period_in_ticks - Timer period in ticks
• auto_reload - true for periodic, false for one-shot
• param - Optional parameter passed to callback
• callback - Function called when timer expires

Returns

• Ok(Self) - Successfully created timer
• Err(Error) - Creation failed

Examples

use osal_rs::os::{Timer, TimerFn};
 
let timer = Timer::new(
    "my_timer",
    1000,
    false,
    None,
    |_timer, _param| Ok(None)
).unwrap();
``

Trait Implementations

impl Clone for Timer

fn clone(&self) -> Timer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Timer

Formats the timer for debugging purposes.

Shows the timer handle and name.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Timer

Allows dereferencing to the underlying FreeRTOS timer handle.

type Target = *const c_void

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for Timer

Formats the timer for display purposes.

Shows a concise representation with name and handle.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Timer

Automatically deletes the timer when it goes out of scope.

This ensures proper cleanup of FreeRTOS resources by calling delete(0) when the timer is dropped.

fn drop(&mut self)

Executes the destructor for this type.

impl Timer for Timer

fn start(&self, ticks_to_wait: TickType) -> OsalRsBool

Starts the timer.

Sends a command to the timer daemon to start the timer. If the timer was already running, this has no effect.

Parameters

• ticks_to_wait - Maximum time to wait for command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer started successfully
• OsalRsBool::False - Failed to start (command queue full)

Examples

use osal_rs::os::{Timer, TimerFn};
 
let timer = Timer::new("my_timer", 1000, true, None, |_, _| Ok(None)).unwrap();
timer.start(10);  // Wait up to 10 ticks

fn stop(&self, ticks_to_wait: TickType) -> OsalRsBool

Stops the timer.

Sends a command to the timer daemon to stop the timer. The timer will not fire again until it is restarted.

Parameters

• ticks_to_wait - Maximum time to wait for command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer stopped successfully
• OsalRsBool::False - Failed to stop (command queue full)

Examples

use osal_rs::os::{Timer, TimerFn};
 
timer.stop(10);  // Wait up to 10 ticks to stop

fn reset(&self, ticks_to_wait: TickType) -> OsalRsBool

Resets the timer.

Resets the timer’s period. For a one-shot timer that has already expired, this will restart it. For a periodic timer, this resets the period.

Parameters

• ticks_to_wait - Maximum time to wait for command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer reset successfully
• OsalRsBool::False - Failed to reset (command queue full)

Examples

use osal_rs::os::{Timer, TimerFn};
 
// Reset a watchdog timer before it expires
timer.reset(10);

fn change_period( &self, new_period_in_ticks: TickType, new_period_ticks: TickType, ) -> OsalRsBool

Changes the timer period.

Changes the period of a timer that was previously created. The timer must be stopped, or the period will be changed when it next expires.

Parameters

• new_period_in_ticks - New period for the timer in ticks
• new_period_ticks - Maximum time to wait for command to be sent to timer daemon

Returns

• OsalRsBool::True - Period changed successfully
• OsalRsBool::False - Failed to change period (command queue full)

Examples

use osal_rs::os::{Timer, TimerFn};
 
// Change period from 1000 ticks to 500 ticks
timer.change_period(500, 10);

fn delete(&mut self, ticks_to_wait: TickType) -> OsalRsBool

Deletes the timer.

Sends a command to the timer daemon to delete the timer. The timer handle becomes invalid after this call.

Parameters

• ticks_to_wait - Maximum time to wait for command to be sent to timer daemon

Returns

• OsalRsBool::True - Timer deleted successfully
• OsalRsBool::False - Failed to delete (command queue full)

Safety

After calling this function, the timer handle is set to null and should not be used.

Examples

use osal_rs::os::{Timer, TimerFn};
 
let mut timer = Timer::new("temp", 1000, false, None, |_, _| Ok(None)).unwrap();
timer.delete(10);

impl Send for Timer

impl Sync for Timer