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
// SPDX-License-Identifier: MIT OR Apache-2.0
//! Execution hints for guiding executor scheduling decisions.
//!
//! This module provides the [`Hint`] type which allows tasks to communicate
//! their expected runtime characteristics to executors. These hints enable
//! executors to make more informed scheduling decisions, potentially improving
//! overall system performance.
//!
//! # Overview
//!
//! Different types of async tasks have different runtime profiles:
//!
//! - **I/O-bound tasks** spend most of their time waiting for external events
//! (network, disk, timers) and yield frequently
//! - **CPU-bound tasks** spend most of their time computing and may run for
//! extended periods without yielding
//!
//! Executors can use these hints to optimize scheduling. For example, an
//! executor might:
//! - Run CPU-bound tasks on dedicated worker threads
//! - Use work-stealing for I/O-bound tasks
//! - Apply different preemption policies based on the hint
//!
//! # Important Notes
//!
//! - Hints are advisory only; executors may ignore them
//! - Providing incorrect hints won't cause correctness issues but may impact performance
//! - When in doubt, use [`Hint::Unknown`]
//!
//! # Examples
//!
//! ## Marking a CPU-intensive task
//!
//! ```
//! use some_executor::task::{Task, ConfigurationBuilder};
//! use some_executor::hint::Hint;
//!
//! let config = ConfigurationBuilder::new()
//! .hint(Hint::CPU)
//! .build();
//!
//! let task = Task::without_notifications(
//! "compute-hash".to_string(),
//! config,
//! async {
//! // CPU-intensive hashing operation
//! let mut result = 0u64;
//! for i in 0..1_000_000 {
//! result = result.wrapping_add(i);
//! }
//! result
//! },
//! );
//! ```
//!
//! ## Marking an I/O-bound task
//!
//! ```
//! use some_executor::task::{Task, ConfigurationBuilder};
//! use some_executor::hint::Hint;
//!
//! let config = ConfigurationBuilder::new()
//! .hint(Hint::IO)
//! .build();
//!
//! let task = Task::without_notifications(
//! "fetch-data".to_string(),
//! config,
//! async {
//! // This task would typically await network or file operations
//! // that spend most time waiting for I/O
//! "fetched data"
//! },
//! );
//! ```
/// Describes the expected runtime characteristics of a task.
///
/// `Hint` provides guidance to executors about how a task is likely to behave
/// during execution. Executors can use this information to optimize scheduling,
/// but they are not required to act on these hints.
///
/// # Variants
///
/// - [`Unknown`](Hint::Unknown): No information about task behavior (default)
/// - [`IO`](Hint::IO): Task is expected to yield frequently while waiting for I/O
/// - [`CPU`](Hint::CPU): Task is expected to perform intensive computation
///
/// # Examples
///
/// ```
/// use some_executor::hint::Hint;
/// use some_executor::task::{Task, ConfigurationBuilder};
///
/// // CPU-bound task
/// let cpu_config = ConfigurationBuilder::new()
/// .hint(Hint::CPU)
/// .build();
///
/// // I/O-bound task
/// let io_config = ConfigurationBuilder::new()
/// .hint(Hint::IO)
/// .build();
///
/// // Unknown (let executor decide)
/// let default_config = ConfigurationBuilder::new()
/// .hint(Hint::Unknown)
/// .build();
/// ```
///
/// # Non-exhaustive
///
/// This enum is marked `#[non_exhaustive]` to allow for future variants
/// without breaking existing code. Always include a catch-all pattern when
/// matching:
///
/// ```
/// use some_executor::hint::Hint;
///
/// fn describe_hint(hint: Hint) -> &'static str {
/// match hint {
/// Hint::Unknown => "unknown workload",
/// Hint::IO => "I/O-bound workload",
/// Hint::CPU => "CPU-bound workload",
/// _ => "unrecognized hint",
/// }
/// }
/// ```