Lines Matching +full:- +full:- +full:can +full:- +full:if
7 allowed calling context (thread, ISR, pre-kernel), the effect of a call
11 if executing the function reaches a reschedule point
13 if executing the function can cause the invoking thread to sleep
14 :ref:`api_term_no-wait`
15 if a parameter to the function can prevent the invoking thread from
17 :ref:`api_term_isr-ok`
18 if the function can be safely called and will have its specified
20 :ref:`api_term_pre-kernel-ok`
21 if the function can be safely called before the kernel has been fully
25 if the function may return before the operation it initializes is
29 if the calling thread must have supervisor privileges to execute the
40 The reschedule attribute is used on a function that can reach a
44 -------
48 a consequence of a higher-priority thread being made ready. Whether the
69 The sleep attribute is used on a function that can cause the invoking
73 -----------
76 applications that use only non-preemptible threads, because the kernel
77 will not replace a running cooperative-only thread at a reschedule point
83 suspend, wait, or invoke :c:func:`k_yield` before it can complete
84 its operation. This behavior may be mediated by **no-wait**.
91 pre-kernel contexts if and only if invoked in **no-wait** mode.
93 .. _api_term_no-wait:
95 no-wait
98 The no-wait attribute is used on a function that is also **sleep** to
99 indicate that a parameter to the function can force an execution path
103 -----------
105 The paradigmatic case of a no-wait function is a function that takes a
106 timeout, to which :c:macro:`K_NO_WAIT` can be passed. The semantics of
108 long as it can be completed immediately, and to return an error code
109 rather than sleep if it cannot.
111 It is use of the no-wait feature that allows functions like
115 A function with a no-wait path does not imply that taking that path
119 pre-kernel contexts only when the parameter selects the no-wait path.
121 .. _api_term_isr-ok:
123 isr-ok
126 The isr-ok attribute is used on a function to indicate that it works
130 -----------
132 Any function that is not **sleep** is inherently **isr-ok**. Functions
133 that are **sleep** are **isr-ok** if the implementation ensures that the
134 documented behavior is implemented even if called from an interrupt
137 or by documenting that when invoked from a non-thread context the
138 function will return a specific error (generally ``-EWOULDBLOCK``).
140 Note that a function that is **no-wait** is safe to call from interrupt
141 context only when the no-wait path is selected. **isr-ok** functions
142 need not provide a no-wait path.
144 .. _api_term_pre-kernel-ok:
146 pre-kernel-ok
149 The pre-kernel-ok attribute is used on a function to indicate that it
154 -----------
156 This attribute is similar to **isr-ok** in function, but is intended for
161 Generally a function that is **pre-kernel-ok** checks
162 :c:func:`k_is_pre_kernel` when determining whether it can fulfill its
164 :c:func:`k_is_in_isr` so it can be **isr-ok** as well.
171 A function is **async** (i.e. asynchronous) if it may return before the
182 -----------
184 Be aware that **async** is orthogonal to context-switching. Some APIs
189 If a function is both **no-wait** and **async** then selecting the
190 no-wait path only guarantees that the function will not sleep. It does
199 The supervisor attribute is relevant only in user-mode applications, and