Callout

Callouts are Apache Mynewt OS timers.

Description

Callout is a way of setting up an OS timer. When the timer fires, it is delivered as an event to task’s event queue.

User would initialize their callout structure using os_callout_init(), or os_callout_func_init() and then arm it with os_callout_reset().

If user wants to cancel the timer before it expires, they can either use os_callout_reset() to arm it for later expiry, or stop it altogether by calling os_callout_stop().

There are 2 different options for data structure to use. First is struct os_callout, which is a bare-bones version. You would initialize this with os_callout_init().

Second option is struct os_callout_func. This you can use if you expect to have multiple different types of timers in your task, running concurrently. The structure contains a function pointer, and you would call that function from your task’s event processing loop.

Time unit when arming the timer is OS ticks. This rate of this ticker depends on the platform this is running on. You should use OS define OS_TICKS_PER_SEC to convert wallclock time to OS ticks.

Callout timer fires out just once. For periodic timer type of operation you need to rearm it once it fires.

API

void os_callout_init(struct os_callout *cf, struct os_eventq *evq, os_event_fn *ev_cb, void *ev_arg)

Initialize a callout.

Callouts are used to schedule events in the future onto a task’s event queue. Callout timers are scheduled using the os_callout_reset() function. When the timer expires, an event is posted to the event queue specified in os_callout_init(). The event argument given here is posted in the ev_arg field of that event.

Parameters

  • c: The callout to initialize

  • evq: The event queue to post an OS_EVENT_T_TIMER event to

  • timo_func: The function to call on this callout for the host task used to provide multiple timer events to a task (this can be NULL.)

  • ev_arg: The argument to provide to the event when posting the timer.

void os_callout_stop(struct os_callout*)

Stop the callout from firing off, any pending events will be cleared.

Parameters

  • c: The callout to stop

int os_callout_reset(struct os_callout*, os_time_t)

Reset the callout to fire off in ‘ticks’ ticks.

Return

0 on success, non-zero on failure

Parameters

  • c: The callout to reset

  • ticks: The number of ticks to wait before posting an event

os_time_t os_callout_remaining_ticks(struct os_callout*, os_time_t)

Returns the number of ticks which remains to callout.

Return

Number of ticks to first pending callout

Parameters

  • c: The callout to check

  • now: The current time in OS ticks

static inline int os_callout_queued(struct os_callout *c)

Returns whether the callout is pending or not.

Return

1 if queued, 0 if not queued.

Parameters

  • c: The callout to check

struct os_callout
#include <os_callout.h>

Structure containing the definition of a callout, initialized by os_callout_init() and passed to callout functions.

Public Members

struct os_event c_ev

Event to post when the callout expires.

struct os_eventq *c_evq

Pointer to the event queue to post the event to.

os_time_t c_ticks

Number of ticks in the future to expire the callout.