Add doc comments for QoSClass

crates/stdx/src/thread.rs

@@ -94,9 +94,116 @@ impl<T> fmt::Debug for JoinHandle<T> {
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 // Please maintain order from least to most priority for the derived `Ord` impl.
 pub enum QoSClass {
+    // Documentation adapted from https://github.com/apple-oss-distributions/libpthread/blob/67e155c94093be9a204b69637d198eceff2c7c46/include/sys/qos.h#L55
+    //
+    /// TLDR: invisible maintenance tasks
+    ///
+    /// Contract:
+    ///
+    /// * **You do not care about how long it takes for work to finish.**
+    /// * **You do not care about work being deferred temporarily.**
+    ///   (e.g. if the device’s battery is in a critical state)
+    ///
+    /// Examples:
+    ///
+    /// * in a video editor:
+    ///   creating periodic backups of project files
+    /// * in a browser:
+    ///   cleaning up cached sites which have not been accessed in a long time
+    /// * in a collaborative word processor:
+    ///   creating a searchable index of all documents
+    ///
+    /// Use this QoS class for background tasks
+    /// which the user did not initiate themselves
+    /// and which are invisible to the user.
+    /// It is expected that this work will take significant time to complete:
+    /// minutes or even hours.
+    ///
+    /// This QoS class provides the most energy and thermally-efficient execution possible.
+    /// All other work is prioritized over background tasks.
     Background,
+
+    /// TLDR: tasks that don’t block using your app
+    ///
+    /// Contract:
+    ///
+    /// * **Your app remains useful even as the task is executing.**
+    ///
+    /// Examples:
+    ///
+    /// * in a video editor:
+    ///   exporting a video to disk –
+    ///   the user can still work on the timeline
+    /// * in a browser:
+    ///   automatically extracting a downloaded zip file –
+    ///   the user can still switch tabs
+    /// * in a collaborative word processor:
+    ///   downloading images embedded in a document –
+    ///   the user can still make edits
+    ///
+    /// Use this QoS class for tasks which
+    /// may or may not be initiated by the user,
+    /// but whose result is visible.
+    /// It is expected that this work will take a few seconds to a few minutes.
+    /// Typically your app will include a progress bar
+    /// for tasks using this class.
+    ///
+    /// This QoS class provides a balance between
+    /// performance, responsiveness and efficiency.
     Utility,
+
+    /// TLDR: tasks that block using your app
+    ///
+    /// Contract:
+    ///
+    /// * **You need this work to complete
+    ///   before the user can keep interacting with your app.**
+    /// * **Your work will not take more than a few seconds to complete.**
+    ///
+    /// Examples:
+    ///
+    /// * in a video editor:
+    ///   opening a saved project
+    /// * in a browser:
+    ///   loading a list of the user’s bookmarks and top sites
+    ///   when a new tab is created
+    /// * in a collaborative word processor:
+    ///   running a search on the document’s content
+    ///
+    /// Use this QoS class for tasks which were initiated by the user
+    /// and block the usage of your app while they are in progress.
+    /// It is expected that this work will take a few seconds or less to complete;
+    /// not long enough to cause the user to switch to something else.
+    /// Your app will likely indicate progress on these tasks
+    /// through the display of placeholder content or modals.
+    ///
+    /// This QoS class is not energy-efficient.
+    /// Rather, it provides responsiveness
+    /// by prioritizing work above other tasks on the system
+    /// except for critical user-interactive work.
     UserInitiated,
+
+    /// TLDR: render loops and nothing else
+    ///
+    /// Contract:
+    ///
+    /// * **You absolutely need this work to complete immediately
+    ///   or your app will appear to freeze.**
+    /// * **Your work will always complete virtually instantaneously.**
+    ///
+    /// Examples:
+    ///
+    /// * the main thread in a GUI application
+    /// * the update & render loop in a game
+    /// * a secondary thread which progresses an animation
+    ///
+    /// Use this QoS class for any work which, if delayed,
+    /// will make your user interface unresponsive.
+    /// It is expected that this work will be virtually instantaneous.
+    ///
+    /// This QoS class is not energy-efficient.
+    /// Specifying this class is a request to run with
+    /// nearly all available system CPU and I/O bandwidth even under contention.
     UserInteractive,
 }