Add more interfaces.

1. Adds a ThreadBuilderExt trait containing helpful methods for spawning
   a thread with priority. The trait is seamlessly implemented for the
   std::thread::Builder so that it is easy to use.
2. Adds a struct ThreadBuilder which can be used to set the priority and
   stuff much more easily than just calling functions, before starting a
   thread.

Only Linux is supported, the Windows support is coming soon.

Author: iddm

.travis.yml

@@ -11,9 +11,12 @@ keywords = ["thread", "schedule", "priority", "pthread"]
 categories = ["concurrency", "asynchronous", "os"]
 edition = "2018"
 
+[dependencies]
+log = "0.4"
+
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"
 
 [target.'cfg(windows)'.dependencies]
 libc = "0.2"
-winapi = { version = "0.3", features = ["errhandlingapi", "processthreadsapi", "winnt", "minwindef", "winbase"] }
+winapi = { version = "0.3", features = ["errhandlingapi", "processthreadsapi", "winnt", "minwindef", "winbase"] }

Cargo.toml

@@ -18,6 +18,7 @@
 pub mod unix;
 #[cfg(unix)]
 pub use unix::*;
+
 #[cfg(windows)]
 pub mod windows;
 #[cfg(windows)]
@@ -31,19 +32,23 @@ pub enum Error {
     /// Target OS' error type. In most systems it is an integer which
     /// later should be used with target OS' API for understanding the value.
     OS(i32),
-    /// FFI failure
+    /// FFI failure.
     Ffi(&'static str),
 }
 
+/// Platform-specific thread priority value.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub struct ThreadPriorityValue(pub u32);
+
 /// Thread priority enumeration.
-#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
+#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub enum ThreadPriority {
     /// Holds a value representing the minimum possible priority.
     Min,
     /// Holds a specific priority value. Should be in [0; 100] range,
     /// a percentage value. The `u32` value is reserved for different
     /// OS'es support.
-    Specific(u32),
+    Specific(ThreadPriorityValue),
     /// Holds scheduling parameters for Deadline scheduling. These are, in order,
     /// the nanoseconds for runtime, deadline, and period. Please note that the
     /// kernel enforces runtime <= deadline <= period.
@@ -90,3 +95,260 @@ impl Thread {
         })
     }
 }
+
+/// A copy of the [`std::thread::Builder`] builder allowing to set priority settings.
+///
+/// ```rust
+/// use thread_priority::*;
+///
+/// let thread = ThreadBuilder::default()
+///     .name("MyThread")
+///     .priority(ThreadPriority::Max)
+///     .spawn(|result| {
+///         // This is printed out from within the spawned thread.
+///         println!("Set priority result: {:?}", result);
+///         assert!(result.is_ok());
+/// }).unwrap();
+/// thread.join();
+///
+/// // Another example where we don't care about the priority having been set.
+/// let thread = ThreadBuilder::default()
+///     .name("MyThread")
+///     .priority(ThreadPriority::Max)
+///     .spawn_careless(|| {
+///         // This is printed out from within the spawned thread.
+///         println!("We don't care about the priority result.");
+/// }).unwrap();
+/// thread.join();
+/// ```
+#[derive(Clone, Debug, Default, Hash, Eq, PartialEq, Ord, PartialOrd)]
+pub struct ThreadBuilder {
+    name: Option<String>,
+    stack_size: Option<usize>,
+    priority: Option<ThreadPriority>,
+
+    #[cfg(unix)]
+    policy: Option<ThreadSchedulePolicy>,
+    // #[cfg(windows)]
+    // winapi_priority: Option<WinAPIThreadPriority>,
+    // #[cfg(windows)]
+    // boost_enabled: bool,
+    // #[cfg(windows)]
+    // ideal_processor: IdealProcessor,
+}
+
+impl ThreadBuilder {
+    /// Names the thread-to-be. Currently the name is used for identification
+    /// only in panic messages.
+    ///
+    /// The name must not contain null bytes (`\0`).
+    ///
+    /// For more information about named threads, see
+    /// [`std::thread::Builder::name()`].
+    pub fn name<VALUE: Into<String>>(mut self, value: VALUE) -> Self {
+        self.name = Some(value.into());
+        self
+    }
+
+    /// Sets the size of the stack (in bytes) for the new thread.
+    ///
+    /// The actual stack size may be greater than this value if
+    /// the platform specifies a minimal stack size.
+    ///
+    /// For more information about the stack size for threads, see
+    /// [`std::thread::Builder::stack_size()`].
+    pub fn stack_size<VALUE: Into<usize>>(mut self, value: VALUE) -> Self {
+        self.stack_size = Some(value.into());
+        self
+    }
+
+    /// The thread's custom priority.
+    ///
+    /// For more information about the stack size for threads, see
+    /// [`ThreadPriority`].
+    pub fn priority<VALUE: Into<ThreadPriority>>(mut self, value: VALUE) -> Self {
+        self.priority = Some(value.into());
+        self
+    }
+
+    /// The thread's unix scheduling policy.
+    ///
+    /// For more information, see
+    /// [`crate::unix::ThreadSchedulePolicy`] and [`crate::unix::set_thread_priority_and_policy`].
+    #[cfg(unix)]
+    pub fn policy<VALUE: Into<unix::ThreadSchedulePolicy>>(mut self, value: VALUE) -> Self {
+        self.policy = Some(value.into());
+        self
+    }
+
+    /// Spawns a new thread by taking ownership of the `Builder`, and returns an
+    /// [`std::io::Result`] to its [`std::thread::JoinHandle`].
+    ///
+    /// See [`std::thread::Builder::spawn`]
+    pub fn spawn<F, T>(mut self, f: F) -> std::io::Result<std::thread::JoinHandle<T>>
+    where
+        F: FnOnce(Result<(), Error>) -> T,
+        F: Send + 'static,
+        T: Send + 'static,
+    {
+        let priority = self.priority;
+        let policy = self.policy;
+
+        self.build_std().spawn(move || match (priority, policy) {
+            (Some(priority), Some(policy)) => f(set_thread_priority_and_policy(
+                thread_native_id(),
+                priority,
+                policy,
+            )),
+            (Some(priority), None) => f(priority.set_for_current()),
+            (None, Some(_policy)) => {
+                unimplemented!("Setting the policy separately isn't currently supported.");
+            }
+            _ => f(Ok(())),
+        })
+    }
+
+    fn build_std(&mut self) -> std::thread::Builder {
+        let mut builder = std::thread::Builder::new();
+
+        if let Some(name) = &self.name {
+            builder = builder.name(name.to_owned());
+        }
+
+        if let Some(stack_size) = self.stack_size {
+            builder = builder.stack_size(stack_size);
+        }
+
+        builder
+    }
+
+    /// Spawns a new thread by taking ownership of the `Builder`, and returns an
+    /// [`std::io::Result`] to its [`std::thread::JoinHandle`].
+    ///
+    /// See [`std::thread::Builder::spawn`]
+    pub fn spawn_careless<F, T>(self, f: F) -> std::io::Result<std::thread::JoinHandle<T>>
+    where
+        F: FnOnce() -> T,
+        F: Send + 'static,
+        T: Send + 'static,
+    {
+        self.spawn(|priority_set_result| {
+            if let Err(e) = priority_set_result {
+                log::warn!(
+                    "Couldn't set the priority for the thread with Rust Thread ID {:?} named {:?}: {:?}",
+                    std::thread::current().id(),
+                    std::thread::current().name(),
+                    e,
+                );
+            }
+
+            f()
+        })
+    }
+}
+
+/// Adds thread building functions using the priority.
+pub trait ThreadBuilderExt {
+    /// Spawn a thread with set priority. The passed functor `f` is executed in the spawned thread and
+    /// receives as the only argument the result of setting the thread priority.
+    /// See [`std::thread::Builder::spawn`] and [`ThreadPriority::set_for_current`] for more info.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use thread_priority::*;
+    /// use thread_priority::ThreadBuilderExt;
+    ///
+    /// let thread = std::thread::Builder::new()
+    ///     .name("MyNewThread".to_owned())
+    ///     .spawn_with_priority(ThreadPriority::Max, |result| {
+    ///         // This is printed out from within the spawned thread.
+    ///         println!("Set priority result: {:?}", result);
+    ///         assert!(result.is_ok());
+    /// }).unwrap();
+    /// thread.join();
+    /// ```
+    fn spawn_with_priority<F, T>(
+        self,
+        priority: ThreadPriority,
+        f: F,
+    ) -> std::io::Result<std::thread::JoinHandle<T>>
+    where
+        F: FnOnce(Result<(), Error>) -> T,
+        F: Send + 'static,
+        T: Send + 'static;
+}
+
+impl ThreadBuilderExt for std::thread::Builder {
+    fn spawn_with_priority<F, T>(
+        self,
+        priority: ThreadPriority,
+        f: F,
+    ) -> std::io::Result<std::thread::JoinHandle<T>>
+    where
+        F: FnOnce(Result<(), Error>) -> T,
+        F: Send + 'static,
+        T: Send + 'static,
+    {
+        self.spawn(move || f(priority.set_for_current()))
+    }
+}
+
+/// Spawns a thread with the specified priority.
+///
+/// See [`ThreadBuilderExt::spawn_with_priority`].
+///
+/// ```rust
+/// use thread_priority::*;
+///
+/// let thread = spawn(ThreadPriority::Max, |result| {
+///     // This is printed out from within the spawned thread.
+///     println!("Set priority result: {:?}", result);
+///     assert!(result.is_ok());
+/// });
+/// thread.join();
+/// ```
+pub fn spawn<F, T>(priority: ThreadPriority, f: F) -> std::thread::JoinHandle<T>
+where
+    F: FnOnce(Result<(), Error>) -> T,
+    F: Send + 'static,
+    T: Send + 'static,
+{
+    std::thread::spawn(move || f(priority.set_for_current()))
+}
+
+/// Spawns a thread with the specified priority.
+/// This is different from [`spawn`] in a way that the passed function doesn't
+/// need to accept the [`ThreadPriority::set_for_current`] result.
+/// In case of an error, the error is logged using the logging facilities.
+///
+/// See [`spawn`].
+///
+/// ```rust
+/// use thread_priority::*;
+///
+/// let thread = spawn_careless(ThreadPriority::Max, || {
+///     // This is printed out from within the spawned thread.
+///     println!("We don't care about the priority result.");
+/// });
+/// thread.join();
+/// ```
+pub fn spawn_careless<F, T>(priority: ThreadPriority, f: F) -> std::thread::JoinHandle<T>
+where
+    F: FnOnce() -> T,
+    F: Send + 'static,
+    T: Send + 'static,
+{
+    std::thread::spawn(move || {
+        if let Err(e) = priority.set_for_current() {
+            log::warn!(
+                "Couldn't set the priority for the thread with Rust Thread ID {:?} named {:?}: {:?}",
+                std::thread::current().id(),
+                std::thread::current().name(),
+                e,
+            );
+        }
+
+        f()
+    })
+}