temporalio_common_wasm/
priority.rs

1use crate::protos::temporal::api::common;
2
3/// Priority contains metadata that controls relative ordering of task processing
4/// when tasks are backlogged in a queue. Initially, Priority will be used in
5/// activity and workflow task queues, which are typically where backlogs exist.
6/// Other queues in the server (such as transfer and timer queues) and rate
7/// limiting decisions do not use Priority, but may in the future.
8///
9/// Priority is attached to workflows and activities. Activities and child
10/// workflows inherit Priority from the workflow that created them, but may
11/// override fields when they are started or modified.
12///
13/// All fields default to `None`, which means "inherit from the calling workflow"
14/// or, if there is no calling workflow, "use the server default."
15///
16/// Despite being named "Priority", this type also contains fields that
17/// control "fairness" mechanisms.
18///
19/// The overall semantics of Priority are:
20/// (more will be added here later)
21/// 1. First, consider "priority_key": lower number goes first.
22#[derive(Debug, Clone, Default, PartialEq, bon::Builder)]
23#[builder(on(String, into), state_mod(vis = "pub"))]
24#[non_exhaustive]
25pub struct Priority {
26    /// Priority key is a positive integer from 1 to n, where smaller integers
27    /// correspond to higher priorities (tasks run sooner). In general, tasks in
28    /// a queue should be processed in close to priority order, although small
29    /// deviations are possible.
30    ///
31    /// The maximum priority value (minimum priority) is determined by server
32    /// configuration, and defaults to 5.
33    ///
34    /// The server default priority is `(min + max) / 2`. With the default max
35    /// of 5 and min of 1, that comes out to 3.
36    ///
37    /// `None` means inherit from the calling workflow or use the server default.
38    pub priority_key: Option<u32>,
39
40    /// Fairness key is a short string that's used as a key for a fairness
41    /// balancing mechanism. It may correspond to a tenant id, or to a fixed
42    /// string like "high" or "low".
43    ///
44    /// The fairness mechanism attempts to dispatch tasks for a given key in
45    /// proportion to its weight. For example, using a thousand distinct tenant
46    /// ids, each with a weight of 1.0 (the default) will result in each tenant
47    /// getting a roughly equal share of task dispatch throughput.
48    ///
49    /// (Note: this does not imply equal share of worker capacity! Fairness
50    /// decisions are made based on queue statistics, not current worker load.)
51    ///
52    /// As another example, using keys "high" and "low" with weight 9.0 and 1.0
53    /// respectively will prefer dispatching "high" tasks over "low" tasks at a
54    /// 9:1 ratio, while allowing either key to use all worker capacity if the
55    /// other is not present.
56    ///
57    /// All fairness mechanisms, including rate limits, are best-effort and
58    /// probabilistic. The results may not match what a "perfect" algorithm with
59    /// infinite resources would produce. The more unique keys are used, the less
60    /// accurate the results will be.
61    ///
62    /// Fairness keys are limited to 64 bytes.
63    ///
64    /// `None` means inherit from the calling workflow or use the server default
65    /// (empty string).
66    pub fairness_key: Option<String>,
67
68    /// Fairness weight for a task can come from multiple sources for
69    /// flexibility. From highest to lowest precedence:
70    /// 1. Weights for a small set of keys can be overridden in task queue
71    ///    configuration with an API.
72    /// 2. It can be attached to the workflow/activity in this field.
73    /// 3. The server default weight of 1.0 will be used.
74    ///
75    /// Weight values are clamped by the server to the range \[0.001, 1000\].
76    ///
77    /// `None` means inherit from the calling workflow or use the server default
78    /// (1.0).
79    pub fairness_weight: Option<f32>,
80}
81
82impl From<Priority> for common::v1::Priority {
83    fn from(priority: Priority) -> Self {
84        common::v1::Priority {
85            priority_key: priority.priority_key.unwrap_or(0) as i32,
86            fairness_key: priority.fairness_key.unwrap_or_default(),
87            fairness_weight: priority.fairness_weight.unwrap_or(0.0),
88        }
89    }
90}
91
92impl From<common::v1::Priority> for Priority {
93    fn from(priority: common::v1::Priority) -> Self {
94        Self {
95            priority_key: if priority.priority_key == 0 {
96                None
97            } else {
98                Some(priority.priority_key as u32)
99            },
100            fairness_key: if priority.fairness_key.is_empty() {
101                None
102            } else {
103                Some(priority.fairness_key)
104            },
105            fairness_weight: if priority.fairness_weight == 0.0 {
106                None
107            } else {
108                Some(priority.fairness_weight)
109            },
110        }
111    }
112}
temporalio_common_wasm/priority.rs

temporalio_common_wasm/
priority.rs
