Event timers¶

For most MiraOS applications, timers will be essential. The timers are used for checking if a time period has passed, scheduling tasks, etc. The timers are also used by applications to let the OS work with other things or enter low power mode for a time period before resuming execution.

Event timers¶

An event timer, or etimer, is used for scheduling processes to be executed after a period of time. Etimers are used in processes to wait for a time period while the rest of the system can work or enter low power mode. An etimer will send an event to the process when it expires.

Example 1¶

In the following example an etimer is used to pause the execution of the current process for one second before it continues.

This is done in these steps:

Defining a etimer variable (note: this must be static to preserve it over context switches).
Setting the etimer with the etimer_set(...) call. An event will be generated when timer expires.
Telling the process to wait for an event.

PROCESS_THREAD(test_hello, ev, data)
{
  // An event-timer variable. Note that this variable must be static
     in order to preserve the value across yielding.
  static struct etimer et;

  PROCESS_BEGIN();

  while (1) {
    etimer_set(&et, CLOCK_SECOND); // Set the timer to 1 second.
    PROCESS_WAIT_EVENT_UNTIL(etimer_expired(&et));
    printf("Hello, world!\n");
  }

  PROCESS_END();
}

Example 2¶

The second example will use two etimers, one to print a character every 0.5 seconds, and one that prints a newline every 10 seconds.

PROCESS_THREAD(test_print, ev, data)
{
  // Our two timer variables
  static struct etimer et, et2;

  PROCESS_BEGIN();

  etimer_set(&et, CLOCK_SECOND / 2); // Set the timer to 0.5 seconds.
  etimer_set(&et2, CLOCK_SECOND * 10); // Set the timer to 10 seconds.

  while (1) {
    PROCESS_WAIT_EVENT(); // wait for any event
    if (etimer_expired(&et)) {
      etimer_set(&et, CLOCK_SECOND / 2); // reset the timer
      printf(".");
    }
    if (etimer_expired(&et2)) {
      etimer_set(&et2, CLOCK_SECOND * 10); // reset the timer
      printf("\n");
    }
  }

  PROCESS_END();
}

Structs¶

etimer¶

A timer.

This structure is used for declaring a timer. The timer must be set with etimer_set() before it can be used.

Name	Type	Description
`timer`	`struct timer`
`next`	`struct etimer *`
`p`	`struct process *`

Functions¶

etimer_set¶

void etimer_set(struct etimer *et, clock_time_t interval);

Set an event timer.

This function is used to set an event timer for a time sometime in the future. When the event timer expires, the event PROCESS_EVENT_TIMER will be posted to the process that called the etimer_set() function.

Parameters¶

Name	Description
et	A pointer to the event timer.
interval	The interval before the timer expires.

etimer_reset¶

void etimer_reset(struct etimer *et);

Reset an event timer with the same interval as was previously set.

Parameters¶

Name	Description
et	A pointer to the event timer.

This function resets the event timer with the same interval that was given to the event timer with the etimer_set() function. The start point of the interval is the exact time that the event timer last expired. Therefore, this function will cause the timer to be stable over time, unlike the etimer_restart() function.

etimer_reset_with_new_interval¶

void etimer_reset_with_new_interval(struct etimer *et, clock_time_t interval);

Reset an event timer with a new interval.

Parameters¶

Name	Description
et	A pointer to the event timer.
interval	The interval before the timer expires.

This function very similar to etimer_reset. Opposed to etimer_reset it is possible to change the timout. This allows accurate, non-periodic timers without drift.

etimer_restart¶

void etimer_restart(struct etimer *et);

Restart an event timer from the current point in time.

Parameters¶

Name	Description
et	A pointer to the event timer.

This function restarts the event timer with the same interval that was given to the etimer_set() function. The event timer will start at the current time.

Note

A periodic timer will drift if this function is used to reset it. For periodic timers, use the etimer_reset() function instead.

etimer_adjust¶

void etimer_adjust(struct etimer *et, int td);

Adjust the expiration time for an event timer.

Parameters¶

Name	Description
et	A pointer to the event timer.
td	The time difference to adjust the expiration time with.

This function is used to adjust the time the event timer will expire. It can be used to synchronize periodic timers without the need to restart the timer or change the timer interval.

Note

This function should only be used for small adjustments. For large adjustments use etimer_set() instead.

Note

A periodic timer will drift unless the etimer_reset() function is used.

etimer_expiration_time¶

clock_time_t etimer_expiration_time(struct etimer *et);

Get the expiration time for the event timer.

Parameters¶

Name	Description
et	A pointer to the event timer.

Return value¶

The expiration time for the event timer.

This function returns the expiration time for an event timer.

etimer_start_time¶

clock_time_t etimer_start_time(struct etimer *et);

Get the start time for the event timer.

Parameters¶

Name	Description
et	A pointer to the event timer.

Return value¶

The start time for the event timer.

This function returns the start time (when the timer was last set) for an event timer.

etimer_expired¶

int etimer_expired(struct etimer *et);

Check if an event timer has expired.

Parameters¶

Name	Description
et	A pointer to the event timer.

Return value¶

Non-zero if the timer has expired, zero otherwise.

This function tests if an event timer has expired and returns true or false depending on its status.

etimer_stop¶

void etimer_stop(struct etimer *et);

Stop a pending event timer.

Parameters¶

Name	Description
et	A pointer to the pending event timer.

This function stops an event timer that has previously been set with etimer_set() or etimer_reset(). After this function has been called, the event timer will not emit any event when it expires.