embassy_executor_macros/lib.rs
1#![doc = include_str!("../README.md")]
2extern crate proc_macro;
3
4use proc_macro::TokenStream;
5
6mod macros;
7mod util;
8use macros::*;
9
10/// Declares an async task that can be run by `embassy-executor`. The optional `pool_size` parameter can be used to specify how
11/// many concurrent tasks can be spawned (default is 1) for the function.
12///
13///
14/// The following restrictions apply:
15///
16/// * The function must be declared `async`.
17/// * The function must not use generics.
18/// * The optional `pool_size` attribute must be 1 or greater.
19///
20///
21/// ## Examples
22///
23/// Declaring a task taking no arguments:
24///
25/// ``` rust
26/// #[embassy_executor::task]
27/// async fn mytask() {
28/// // Function body
29/// }
30/// ```
31///
32/// Declaring a task with a given pool size:
33///
34/// ``` rust
35/// #[embassy_executor::task(pool_size = 4)]
36/// async fn mytask() {
37/// // Function body
38/// }
39/// ```
40#[proc_macro_attribute]
41pub fn task(args: TokenStream, item: TokenStream) -> TokenStream {
42 task::run(args.into(), item.into()).into()
43}
44
45#[proc_macro_attribute]
46pub fn main_avr(args: TokenStream, item: TokenStream) -> TokenStream {
47 main::run(args.into(), item.into(), &main::ARCH_AVR).into()
48}
49
50/// Creates a new `executor` instance and declares an application entry point for Cortex-M spawning the corresponding function body as an async task.
51///
52/// The following restrictions apply:
53///
54/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
55/// * The function must be declared `async`.
56/// * The function must not use generics.
57/// * Only a single `main` task may be declared.
58///
59/// ## Examples
60/// Spawning a task:
61///
62/// ``` rust
63/// #[embassy_executor::main]
64/// async fn main(_s: embassy_executor::Spawner) {
65/// // Function body
66/// }
67/// ```
68#[proc_macro_attribute]
69pub fn main_cortex_m(args: TokenStream, item: TokenStream) -> TokenStream {
70 main::run(args.into(), item.into(), &main::ARCH_CORTEX_M).into()
71}
72
73/// Creates a new `executor` instance and declares an application entry point for Cortex-A/R
74/// spawning the corresponding function body as an async task.
75///
76/// The following restrictions apply:
77///
78/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it
79/// can use to spawn additional tasks.
80/// * The function must be declared `async`.
81/// * The function must not use generics.
82/// * Only a single `main` task may be declared.
83///
84/// ## Examples
85/// Spawning a task:
86///
87/// ``` rust
88/// #[embassy_executor::main]
89/// async fn main(_s: embassy_executor::Spawner) {
90/// // Function body
91/// }
92/// ```
93#[proc_macro_attribute]
94pub fn main_cortex_ar(args: TokenStream, item: TokenStream) -> TokenStream {
95 main::run(args.into(), item.into(), &main::ARCH_CORTEX_AR).into()
96}
97
98/// Creates a new `executor` instance and declares an architecture agnostic application entry point spawning
99/// the corresponding function body as an async task.
100///
101/// The following restrictions apply:
102///
103/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
104/// * The function must be declared `async`.
105/// * The function must not use generics.
106/// * Only a single `main` task may be declared.
107///
108/// A user-defined entry macro must provided via the `entry` argument
109///
110/// ## Examples
111/// Spawning a task:
112/// ``` rust
113/// #[embassy_executor::main(entry = "qingke_rt::entry")]
114/// async fn main(_s: embassy_executor::Spawner) {
115/// // Function body
116/// }
117/// ```
118#[proc_macro_attribute]
119pub fn main_spin(args: TokenStream, item: TokenStream) -> TokenStream {
120 main::run(args.into(), item.into(), &main::ARCH_SPIN).into()
121}
122
123/// Creates a new `executor` instance and declares an application entry point for RISC-V spawning the corresponding function body as an async task.
124///
125/// The following restrictions apply:
126///
127/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
128/// * The function must be declared `async`.
129/// * The function must not use generics.
130/// * Only a single `main` task may be declared.
131///
132/// A user-defined entry macro can be optionally provided via the `entry` argument to override the default of `riscv_rt::entry`.
133///
134/// ## Examples
135/// Spawning a task:
136///
137/// ``` rust
138/// #[embassy_executor::main]
139/// async fn main(_s: embassy_executor::Spawner) {
140/// // Function body
141/// }
142/// ```
143///
144/// Spawning a task using a custom entry macro:
145/// ``` rust
146/// #[embassy_executor::main(entry = "esp_riscv_rt::entry")]
147/// async fn main(_s: embassy_executor::Spawner) {
148/// // Function body
149/// }
150/// ```
151#[proc_macro_attribute]
152pub fn main_riscv(args: TokenStream, item: TokenStream) -> TokenStream {
153 main::run(args.into(), item.into(), &main::ARCH_RISCV).into()
154}
155
156/// Creates a new `executor` instance and declares an application entry point for STD spawning the corresponding function body as an async task.
157///
158/// The following restrictions apply:
159///
160/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
161/// * The function must be declared `async`.
162/// * The function must not use generics.
163/// * Only a single `main` task may be declared.
164///
165/// ## Examples
166/// Spawning a task:
167///
168/// ``` rust
169/// #[embassy_executor::main]
170/// async fn main(_s: embassy_executor::Spawner) {
171/// // Function body
172/// }
173/// ```
174#[proc_macro_attribute]
175pub fn main_std(args: TokenStream, item: TokenStream) -> TokenStream {
176 main::run(args.into(), item.into(), &main::ARCH_STD).into()
177}
178
179/// Creates a new `executor` instance and declares an application entry point for WASM spawning the corresponding function body as an async task.
180///
181/// The following restrictions apply:
182///
183/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
184/// * The function must be declared `async`.
185/// * The function must not use generics.
186/// * Only a single `main` task may be declared.
187///
188/// ## Examples
189/// Spawning a task:
190///
191/// ``` rust
192/// #[embassy_executor::main]
193/// async fn main(_s: embassy_executor::Spawner) {
194/// // Function body
195/// }
196/// ```
197#[proc_macro_attribute]
198pub fn main_wasm(args: TokenStream, item: TokenStream) -> TokenStream {
199 main::run(args.into(), item.into(), &main::ARCH_WASM).into()
200}
201
202/// Creates a new `executor` instance and declares an application entry point for an unspecified architecture, spawning the corresponding function body as an async task.
203///
204/// The following restrictions apply:
205///
206/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
207/// * The function must be declared `async`.
208/// * The function must not use generics.
209/// * Only a single `main` task may be declared.
210///
211/// A user-defined entry macro and executor type must be provided via the `entry` and `executor` arguments of the `main` macro.
212///
213/// ## Examples
214/// Spawning a task:
215/// ``` rust
216/// #[embassy_executor::main(entry = "your_hal::entry", executor = "your_hal::Executor")]
217/// async fn main(_s: embassy_executor::Spawner) {
218/// // Function body
219/// }
220/// ```
221#[proc_macro_attribute]
222pub fn main_unspecified(args: TokenStream, item: TokenStream) -> TokenStream {
223 main::run(args.into(), item.into(), &main::ARCH_UNSPECIFIED).into()
224}