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 struct os_callout using os_callout_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().

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 *c, 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

  • ev_cb – 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 *c)

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 *c, os_time_t ticks)

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

Parameters:

  • c – The callout to reset

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

Returns:

0 on success; non-zero on failure

os_time_t os_callout_remaining_ticks(struct os_callout *c, os_time_t now)

Returns the number of ticks which remains to callout.

Parameters:

  • c – The callout to check

  • now – The current time in OS ticks

Returns:

Number of ticks to first pending callout

static inline int os_callout_queued(struct os_callout *c)

Returns whether the callout is pending or not.

Parameters:

  • c – The callout to check

Returns:

1 if queued; 0 if not queued.

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 Functions

TAILQ_ENTRY (os_callout) c_next

Next callout in the list.

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.