Lines Matching +full:one +full:- +full:timer +full:- +full:only
6 A :dfn:`timer` is a kernel object that measures the passage of time
7 using the kernel's system clock. When a timer's specified time limit
8 is reached it can perform an application-defined action,
19 Any number of timers can be defined (limited only by available RAM). Each timer
22 A timer has the following key properties:
24 * A **duration** specifying the time interval before the timer
28 * A **period** specifying the time interval between all timer
29 expirations after the first one, also a :c:type:`k_timeout_t`. It must be
30 non-negative. A period of ``K_NO_WAIT`` (i.e. zero) or
31 ``K_FOREVER`` means that the timer is a one-shot timer that stops
32 after a single expiration. (For example then, if a timer is started
36 * An **expiry function** that is executed each time the timer expires.
40 * A **stop function** that is executed if the timer is stopped prematurely
41 while running. The function is executed by the thread that stops the timer.
44 * A **status** value that indicates how many times the timer has expired
47 A timer must be initialized before it can be used. This specifies its
48 expiry function and stop function values, sets the timer's status to zero,
49 and puts the timer into the **stopped** state.
51 A timer is **started** by specifying a duration and a period.
52 The timer's status is reset to zero, and then the timer enters
55 Note that the timer's duration and period parameters specify
56 **minimum** delays that will elapse. Because of internal system timer
62 When a running timer expires its status is incremented
63 and the timer executes its expiry function, if one exists;
64 If a thread is waiting on the timer, it is unblocked.
65 If the timer's period is zero the timer enters the stopped state;
66 otherwise, the timer restarts with a new duration equal to its period.
68 A running timer can be stopped in mid-countdown, if desired.
69 The timer's status is left unchanged, then the timer enters the stopped state
70 and executes its stop function, if one exists.
71 If a thread is waiting on the timer, it is unblocked.
72 Attempting to stop a non-running timer is permitted,
73 but has no effect on the timer since it is already stopped.
75 A running timer can be restarted in mid-countdown, if desired.
76 The timer's status is reset to zero, then the timer begins counting down
78 If a thread is waiting on the timer, it continues waiting.
80 A timer's status can be read directly at any time to determine how many times
81 the timer has expired since its status was last read.
82 Reading a timer's status resets its value to zero.
83 The amount of time remaining before the timer expires can also be read;
84 a value of zero indicates that the timer is stopped.
86 A thread may read a timer's status indirectly by **synchronizing**
87 with the timer. This blocks the thread until the timer's status is non-zero
88 (indicating that it has expired at least once) or the timer is stopped;
89 if the timer status is already non-zero or the timer is already stopped
91 returns the timer's status and resets it to zero.
94 Only a single user should examine the status of any given timer,
96 Similarly, only a single thread at a time should synchronize
97 with a given timer. ISRs are not permitted to synchronize with timers,
103 Defining a Timer
106 A timer is defined using a variable of type :c:struct:`k_timer`.
109 The following code defines and initializes a timer.
111 .. code-block:: c
118 Alternatively, a timer can be defined and initialized at compile time
123 .. code-block:: c
127 Using a Timer Expiry Function
130 The following code uses a timer to perform a non-trivial action on a periodic
132 the timer's expiry function submits a work item to the
135 .. code-block:: c
154 /* start a periodic timer that expires once every second */
157 Reading Timer Status
160 The following code reads a timer's status directly to determine
161 if the timer has expired or not.
163 .. code-block:: c
169 /* start a one-shot timer that expires after 200 ms */
175 /* check timer status */
177 /* timer has expired */
179 /* timer was stopped (by someone else) before expiring */
181 /* timer is still running */
184 Using Timer Status Synchronization
187 The following code performs timer status synchronization to allow a thread
191 .. code-block:: c
200 /* start a one-shot timer that expires after 500 ms */
206 /* ensure timer has expired (waiting for expiry, if necessary) */
214 between the two protocol operations, without using a timer.
219 Use a timer to initiate an asynchronous operation after a specified
222 Use a timer to determine whether or not a specified amount of time has
227 Use a timer to perform other work while carrying out operations
233 directly, rather than using a timer.