1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
//! # Orcher Rust SDK
//!
//! Build durable workflows and tasks for the Orcher workflow engine.
//!
//! Workflows are async functions whose progress the engine records, so they
//! survive crashes and restarts and resume where they left off. Tasks are the
//! steps that touch the outside world, and are retried under a policy when they
//! fail. A [`Worker`] polls the engine and runs both; a [`Client`] starts
//! workflows and reads their results.
//!
//! ## Quick start
//!
//! ```rust,no_run
//! use orcher_sdk::prelude::*;
//!
//! // A worker is I/O-bound, so a single-threaded runtime is enough.
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<()> {
//! let worker = Worker::builder()
//! .server_url("http://localhost:50051")
//! .task_queue("my-queue")
//! .build()
//! .await?;
//!
//! worker.run().await
//! }
//! ```
//!
//! ## Tokio runtime
//!
//! A worker spends its time waiting on gRPC long-polls, so the single-threaded
//! runtime (`#[tokio::main(flavor = "current_thread")]`) is recommended: its
//! event loop sleeps while it waits, whereas the multi-threaded work-stealing
//! scheduler keeps its threads busy even when the worker is idle.
//!
//! Run CPU-heavy work with `tokio::task::spawn_blocking()`, which uses a
//! separate thread pool and does not hold up the event loop:
//!
//! ```rust
//! use orcher_sdk::prelude::*;
//!
//! #[task]
//! async fn checksum(_ctx: TaskContext, data: Vec<u8>) -> Result<u64> {
//! let sum = tokio::task::spawn_blocking(move || {
//! // CPU-intensive work here.
//! data.iter().map(|&b| u64::from(b)).sum::<u64>()
//! })
//! .await
//! .map_err(|e| Error::Other(e.to_string()))?;
//! Ok(sum)
//! }
//! ```
//!
//! ## Modules
//!
//! - [`workflow`](mod@workflow): the workflow context and the durable operations it offers
//! - [`task`](mod@task): the task context, retry policies and task options
//! - [`actor`](mod@actor): keyed actors with durable state
//! - [`worker`]: building and running a worker
//! - [`client`]: starting, querying and sending events to workflows
//! - [`error`]: the SDK's error types
//! - [`prelude`]: the imports most programs need
// Re-exported so that macro-generated `#[::orcher_sdk::ctor::ctor]` resolves in user crates.
pub extern crate ctor;
/// Crates that macro-generated code names through `::orcher_sdk::__private`, so a crate
/// using the macros needs no dependency on them. Not public API.
pub use ;
pub use Client;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use NamespaceInfo;
pub use ;
pub use Payload;
/// The imports most programs need.
///
/// ```rust
/// use orcher_sdk::prelude::*;
/// ```
///
/// # Result type
///
/// Workflows and tasks must return [`orcher_sdk::Result`](crate::Result), which the
/// prelude exports, not `anyhow::Result`. Converting through `anyhow::Error`
/// loses the error's type, and the worker relies on that type to tell a
/// workflow that is suspending from one that has failed. An explicit
/// `use anyhow::Result;` overrides the prelude's `Result`, so do not import both
/// in workflow and task modules.
/// The version of this crate.
pub const VERSION: &str = env!;
/// The name this SDK reports itself under.
pub const SDK_NAME: &str = "orcher-rust-sdk";
/// Calls the crate's generated `__orcher_force_registration()` function.
///
/// Most programs do not need this macro. With the `auto-register` feature,
/// every `#[task]` and `#[workflow]` registers itself when the program starts,
/// and [`WorkerBuilder::new`] collects them.
///
/// The macro is for crates that generate explicit registration code instead:
/// a build script writes `$OUT_DIR/auto_register.rs` defining
/// `__orcher_force_registration()`, and the crate root includes it with
/// `include!(concat!(env!("OUT_DIR"), "/auto_register.rs"));`. Without that
/// function in scope, the macro fails to compile with a "not found" error.
///
/// # Example
///
/// ```rust,no_run
/// use orcher_sdk::prelude::*;
///
/// #[task]
/// async fn my_task(ctx: TaskContext, input: String) -> Result<String> {
/// Ok(format!("Processed: {}", input))
/// }
///
/// #[workflow]
/// async fn my_workflow(ctx: WorkflowContext, input: String) -> Result<String> {
/// Ok(input)
/// }
///
/// // Defines `__orcher_force_registration()`; written by the build script.
/// // include!(concat!(env!("OUT_DIR"), "/auto_register.rs"));
/// # fn __orcher_force_registration() {}
///
/// #[tokio::main]
/// async fn main() -> Result<()> {
/// // Registers my_task and my_workflow.
/// orcher_sdk::initialize_handlers!();
///
/// let service = Worker::builder()
/// .server_url("http://localhost:50051")
/// .build()
/// .await?;
///
/// service.run().await
/// }
/// ```
/// Fails to compile: `initialize_handlers!` requires the `auto-register` feature.