os::rtos::timer Class Reference

User single-shot or periodic timer. More...

#include <cmsis-plus/rtos/os.h>

Inheritance diagram for os::rtos::timer:

Classes
class	attributes
	Timer attributes. More...
class	attributes_periodic
	Periodic timer attributes. More...
struct	run
	Timer run types. More...
struct	state
	Timer states. More...

Public Types
using	func_args_t = void *
	Timer call back function arguments.
using	func_t = void(*)(func_args_t args)
	Entry point of a timer call back function.
using	state_t = uint8_t
	Type of of variables holding timer states.
using	type_t = uint8_t
	Type of of variables holding timer run types.

Public Member Functions
Constructors & Destructor
	timer (func_t function, func_args_t args, const attributes &attr=once_initializer)
	Construct a timer object instance.
	timer (const char *name, func_t function, func_args_t args, const attributes &attr=once_initializer)
	Construct a named timer object instance.
	~timer ()
	Destruct the timer object instance.
Operators
bool	operator== (const timer &rhs) const
	Compare timers.
Public Member Functions
result_t	start (clock::duration_t period)
	Start or restart the timer.
result_t	stop (void)
	Stop the timer.
Public Member Functions
const char *	name (void) const
	Get object name.

Static Public Member Functions
Operators
static void *	operator new (std::size_t bytes)
	Allocate space for a new object instance using the RTOS system allocator.
static void *	operator new (std::size_t bytes, void *ptr)
	Emplace a new object instance.
static void *	operator new[] (std::size_t bytes)
	Allocate space for an array of new object instances using the RTOS system allocator.
static void *	operator new[] (std::size_t bytes, void *ptr)
	Emplace an array of new object instances.
static void	operator delete (void *ptr, std::size_t bytes)
	Deallocate the dynamically allocated object instance. using the RTOS system allocator.
static void	operator delete[] (void *ptr, std::size_t bytes)
	Deallocate the dynamically allocated array of object. instances using the RTOS system allocator.

Static Public Attributes
static const attributes	once_initializer
	Default one shot timer initialiser.
static const attributes_periodic	periodic_initializer
	Default periodic timer initialiser.

Detailed Description

The CMISIS++ timer schedules the execution of a user function after a programmable interval. If the timer is periodic, the function is rescheduled automatically until the timer is stopped.

Example

#include <cmsis-plus/rtos/os.h>
#include <cstdlib>
 
using namespace os::rtos;
 
// Thread function.
void
func(void* args)
{
  // Do something.
  ...
}
 
int
os_main(int argc, char* argv[])
{
  // Construct new thread, with function and no arguments.
  timer tm { func, nullptr };
 
  // Schedule func() to be executed after 100 ticks.
  tm.start(100);
 
  // Do something.
 
  return 0;
}

POSIX compatibility

No POSIX similar functionality identified.

Definition at line 55 of file os-timer.h.

Constructor & Destructor Documentation

timer() [1/2]

os::rtos::timer::timer	(	func_t	function,
		func_args_t	args,
		const attributes &	attr = once_initializer
	)

Parameters

[in]	function	Pointer to timer function.
[in]	args	Pointer to timer function arguments.
[in]	attr	Reference to attributes.

This constructor shall initialise a timer object with attributes referenced by attr. If the attributes specified by attr are modified later, the timer attributes shall not be affected.

Upon successful initialisation, the state of the timer object shall become initialised.

Only the timer object itself may be used for running the function. It is not allowed to make copies of timer objects.

In cases where default condition variable attributes are appropriate, the variables timer::once_initializer or timer::periodic_initializer can be used to initialise timers. The effect shall be equivalent to creating a timer object with the simple constructor.

If the attr attributes are modified after the timer creation, the timer attributes shall not be affected.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 135 of file os-timer.cpp.

        : timer{ nullptr, function, args, attr }
    {
    }

timer() [2/2]

os::rtos::timer::timer	(	const char *	name,
		func_t	function,
		func_args_t	args,
		const attributes &	attr = once_initializer
	)

Parameters

[in]	name	Pointer to name.
[in]	function	Pointer to timer function.
[in]	args	Pointer to timer function arguments.
[in]	attr	Reference to attributes.

This constructor shall initialise a named timer object with attributes referenced by attr. If the attributes specified by attr are modified later, the timer attributes shall not be affected.

Upon successful initialisation, the state of the timer object shall become initialised.

Only the timer object itself may be used for running the function. It is not allowed to make copies of timer objects.

In cases where default condition variable attributes are appropriate, the variables timer::once_initializer or timer::periodic_initializer can be used to initialise timers. The effect shall be equivalent to creating a timer object with the simple constructor.

If the attr attributes are modified after the timer creation, the timer attributes shall not be affected.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 166 of file os-timer.cpp.

        : object_named_system{ name }
    {
#if defined(OS_TRACE_RTOS_TIMER)
      trace::printf ("%s() @%p %s\n", __func__, this, this->name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_throw (!interrupts::in_handler_mode (), EPERM);
      // Don't call this from critical regions.
      os_assert_throw (function != nullptr, EINVAL);
 
      type_ = attr.tm_type;
      func_ = function;
      func_args_ = args;
 
#if !defined(OS_USE_RTOS_PORT_TIMER)
      clock_ = attr.clock != nullptr ? attr.clock : &sysclock;
#endif
 
#if defined(OS_USE_RTOS_PORT_TIMER)
 
      port::timer::create (this, function, args);
 
#else
 
      period_ = 0;
 
#endif
      state_ = state::initialized;
    }

References os::rtos::internal::attributes_clocked::clock, os::rtos::interrupts::in_handler_mode(), os::rtos::timer::state::initialized, os_assert_throw, os::trace::printf(), os::rtos::sysclock, and os::rtos::timer::attributes::tm_type.

~timer()

os::rtos::timer::~timer

(

)

This destructor shall destroy the timer object; the object becomes, in effect, uninitialised. An implementation may cause the destructor to set the object to an invalid value.

If the timer is running, it must be automatically stopped.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 209 of file os-timer.cpp.

    {
#if defined(OS_TRACE_RTOS_TIMER)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
#if defined(OS_USE_RTOS_PORT_TIMER)
 
      port::timer::destroy (this);
 
#else
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        if (state_ == state::running)
          {
            timer_node_.unlink ();
          }
        // ----- Exit critical section ----------------------------------------
      }
 
#endif
      state_ = state::destroyed;
    }

References os::rtos::timer::state::destroyed, os::rtos::internal::object_named::name(), os::trace::printf(), and os::rtos::timer::state::running.

Member Function Documentation

name()

const char * os::rtos::internal::object_named::name ( void  ) const

inlineinherited

Parameters

None.

Returns

A null terminated string.

All objects return a non-null string; anonymous objects return "-".

Note

Can be invoked from Interrupt Service Routines.

Definition at line 753 of file os-decls.h.

      {
        return name_;
      }

Referenced by os::memory::lifo::lifo(), os::memory::malloc_memory_resource::malloc_memory_resource(), os::rtos::message_queue_typed< T, Allocator >::message_queue_typed(), os::memory::block_pool::~block_pool(), os::rtos::event_flags::~event_flags(), os::memory::first_fit_top::~first_fit_top(), os::memory::lifo::~lifo(), os::memory::malloc_memory_resource::~malloc_memory_resource(), os::rtos::memory_pool::~memory_pool(), os::rtos::message_queue::~message_queue(), os::rtos::mutex::~mutex(), os::rtos::semaphore::~semaphore(), os::rtos::thread::~thread(), ~timer(), os::rtos::memory_pool::alloc(), os::rtos::thread::cancel(), os::rtos::event_flags::clear(), os::rtos::mutex::consistent(), os::rtos::thread::detach(), os::memory::new_delete_memory_resource::do_allocate(), os::memory::block_pool::do_allocate(), os::memory::first_fit_top::do_allocate(), os::memory::lifo::do_allocate(), os::memory::malloc_memory_resource::do_allocate(), os::rtos::thread::flags_raise(), os::rtos::memory_pool::free(), os::rtos::event_flags::get(), os::rtos::thread::interrupt(), os::rtos::thread::join(), os::rtos::thread::kill(), os::rtos::internal::terminated_threads_list::link(), os::rtos::mutex::lock(), os::rtos::memory::memory_resource::out_of_memory_handler(), os::rtos::semaphore::post(), os::rtos::mutex::prio_ceiling(), os::rtos::mutex::prio_ceiling(), os::rtos::thread::priority(), os::rtos::thread::priority_inherited(), os::rtos::event_flags::raise(), os::rtos::message_queue::receive(), os::rtos::memory_pool::reset(), os::rtos::message_queue::reset(), os::rtos::mutex::reset(), os::rtos::semaphore::reset(), os::rtos::thread::resume(), os::rtos::message_queue::send(), os::rtos::clock::sleep_for(), start(), stop(), os::rtos::memory_pool::timed_alloc(), os::rtos::mutex::timed_lock(), os::rtos::message_queue::timed_receive(), os::rtos::message_queue::timed_send(), os::rtos::semaphore::timed_wait(), os::rtos::event_flags::timed_wait(), os::rtos::memory::memory_resource::trace_print_statistics(), os::rtos::memory_pool::try_alloc(), os::rtos::mutex::try_lock(), os::rtos::message_queue::try_receive(), os::rtos::message_queue::try_send(), os::rtos::event_flags::try_wait(), os::rtos::semaphore::try_wait(), os::rtos::internal::ready_threads_list::unlink_head(), os::rtos::mutex::unlock(), os::rtos::event_flags::wait(), os::rtos::semaphore::wait(), and os::rtos::event_flags::waiting().

operator delete()

void os::rtos::internal::object_named_system::operator delete ( void *  ptr, std::size_t  bytes  )

inlinestaticinherited

Parameters

ptr	Pointer to object.
bytes	Number of bytes to deallocate.

Returns

Nothing.

The deallocation function (3.7.4.2) called by a delete-expression to render the value of ptr invalid.

ptr shall be a null pointer or its value shall be a value returned by an earlier call to the (possibly replaced) operator new() which has not been invalidated by an intervening call to operator delete(void*).

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 120 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        rtos::memory::allocator<char> ().deallocate (static_cast<char*> (ptr),
                                                     bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::deallocate(), and os::rtos::interrupts::in_handler_mode().

operator delete[]()

void os::rtos::internal::object_named_system::operator delete[] ( void *  ptr, std::size_t  bytes  )

inlinestaticinherited

Parameters

ptr	Pointer to array of objects.
bytes	Number of bytes to deallocate.

Returns

Nothing.

The deallocation function (3.7.4.2) called by the array form of a delete-expression to render the value of ptr invalid.

If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier call to operator new.

The storage is deallocated using the RTOS system allocator.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 141 of file os-inlines.h.

      {
        // Forward array deallocation to single element deallocation.
        operator delete (ptr, bytes);
      }

operator new() [1/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes )

inlinestaticinherited

Parameters

bytes

Number of bytes to allocate.

Returns

Pointer to allocated object.

The allocation function (3.7.4.1) called by a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 43 of file os-inlines.h.

      {
        assert (!interrupts::in_handler_mode ());
 
        return rtos::memory::allocator<char> ().allocate (bytes);
      }

References os::rtos::memory::allocator_stateless_default_resource< T >::allocate(), and os::rtos::interrupts::in_handler_mode().

operator new() [2/2]

void * os::rtos::internal::object_named_system::operator new ( std::size_t  bytes, void *  ptr  )

inlinestaticinherited

Parameters

bytes	Number of bytes to emplace.
ptr	Pointer to location to emplace the object.

Returns

Pointer to emplaced object.

The allocation function (3.7.4.1) called by a placement new-expression to allocate a storage of size bytes suitably aligned to represent any object of that size. Return a non-null pointer to suitably aligned storage (3.7.4).

The storage is allocated using the RTOS system allocator.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 80 of file os-inlines.h.

      {
        return ptr;
      }

operator new[]() [1/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes )

inlinestaticinherited

Parameters

bytes

Number of bytes to allocate.

Returns

Pointer to allocated array.

The allocation function (3.7.4.1) called by the array form of a new-expression (5.3.4) to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 61 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes);
      }

operator new[]() [2/2]

void * os::rtos::internal::object_named_system::operator new[] ( std::size_t  bytes, void *  ptr  )

inlinestaticinherited

Parameters

bytes	Number of bytes to emplace.
ptr	Pointer to location to emplace the object.

Returns

Pointer to emplaced array.

The allocation function (3.7.4.1) called by the array form of a placement new-expression to allocate a storage of size bytes suitably aligned to represent any array object of that size or smaller.

The storage is allocated using the RTOS system allocator.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 97 of file os-inlines.h.

      {
        // Forward array allocation to single element allocation.
        return operator new (bytes, ptr);
      }

operator==()

bool os::rtos::timer::operator== ( const timer &  rhs ) const

inline

Return values

true	The given timer is the same as this timer.
false	The timers are different.

Identical timers should have the same memory address.

Definition at line 474 of file os-timer.h.

    {
      return this == &rhs;
    }

start()

result_t os::rtos::timer::start

(

clock::duration_t

period

)

Parameters

[in]

period

Timer period, in clock units (ticks or seconds).

Return values

result::ok	The timer has been started or restarted.
ENOTRECOVERABLE	Timer could not be started.
EPERM	Cannot be invoked from an Interrupt Service Routines.

If the period is 0, it is automatically adjusted to 1.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 243 of file os-timer.cpp.

    {
#if defined(OS_TRACE_RTOS_TIMER)
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
      trace::printf ("%s(%u) @%p %s\n", __func__,
                     static_cast<unsigned int> (period), this, name ());
#pragma GCC diagnostic pop
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      if (period == 0)
        {
          period = 1;
        }
 
      result_t res;
 
#if defined(OS_USE_RTOS_PORT_TIMER)
 
      res = port::timer::start (this, period);
 
#else
 
      period_ = period;
 
      timer_node_.timestamp = clock_->steady_now () + period;
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        // If started, stop.
        timer_node_.unlink ();
 
        clock_->steady_list ().link (timer_node_);
        // ----- Exit critical section ----------------------------------------
      }
      res = result::ok;
 
#endif
 
      if (res == result::ok)
        {
          state_ = state::running;
        }
      return res;
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, os::trace::printf(), and os::rtos::timer::state::running.

stop()

result_t os::rtos::timer::stop

(

void

)

Parameters

None.

Return values

result::ok	The timer has been stopped.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EAGAIN	The timer is not yet started.
ENOTRECOVERABLE	Timer could not be stopped.

Remove the timer from the clock schedule list, so that the next execution of the function is cancelled.

A stopped timer can be restarted later with start()`.

Warning

Cannot be invoked from Interrupt Service Routines.

Definition at line 307 of file os-timer.cpp.

    {
#if defined(OS_TRACE_RTOS_TIMER)
      trace::printf ("%s() @%p %s\n", __func__, this, name ());
#endif
 
      // Don't call this from interrupt handlers.
      os_assert_err (!interrupts::in_handler_mode (), EPERM);
 
      if (state_ != state::running)
        {
          return EAGAIN;
        }
 
      result_t res;
 
#if defined(OS_USE_RTOS_PORT_TIMER)
 
      res = port::timer::stop (this);
 
#else
 
      {
        // ----- Enter critical section ---------------------------------------
        interrupts::critical_section ics;
 
        timer_node_.unlink ();
        // ----- Exit critical section ----------------------------------------
      }
      res = result::ok;
 
#endif
 
      state_ = state::stopped;
      return res;
    }

References os::rtos::interrupts::in_handler_mode(), os::rtos::internal::object_named::name(), os::rtos::result::ok, os_assert_err, os::trace::printf(), os::rtos::timer::state::running, and os::rtos::timer::state::stopped.

Member Data Documentation

once_initializer

const timer::attributes os::rtos::timer::once_initializer

static

This variable can be used to create a single run timer.

Definition at line 200 of file os-timer.h.

---

The documentation for this class was generated from the following files:

• os-timer.h
• os-timer.cpp