Yield fixes

CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog],
+and this project adheres to [Semantic Versioning].
+
+This project is currently in early [pre-release], and there may be arbitrary breaking changes between pre-release versions.
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
+[Semantic Versioning]: https://semver.org/spec/v2.0.0.html
+[pre-release]: https://semver.org/spec/v2.0.0.html#spec-item-9
+
+## [Unreleased]
+
+### Added
+
+- `ThreadPool::claim_lease` method.
+- `shuttle` test suite and feature flag (temporarily disabled).
+
+### Changed
+
+- Rename `ThreadPool::as_worker` to `ThreadPool::with_worker`.
+- Make `Scope` public.
+- Make `Yield` public. 
+- Improved safety comments for `scope`.
+- Code format no longer requires nightly.
+
+### Removed
+
+- `loom` cfg flag and test suite.
+
+### Fixed 
+
+- Fixed some broken examples and doc-tests.
+- Various broken links, spelling mistakes, and indentations.
+- Documentation for `yield_now` and `yield_local`.
+
+## [1.0.0-alpha.2]
+
+This was the first usable build of forte, and is the start point for this change log. All subsequent changes are relative to this pre-release.
+
+## [1.0.0-alpha.1]
+
+The initial release of this library was intended only to claim the name on `crates.io`. It was still early in development and did not employ a change-log.

src/lib.rs

@@ -47,6 +47,7 @@ mod thread_pool;
 pub use scope::Scope;
 pub use thread_pool::ThreadPool;
 pub use thread_pool::Worker;
+pub use thread_pool::Yield;
 pub use thread_pool::block_on;
 pub use thread_pool::join;
 pub use thread_pool::scope;

src/thread_pool.rs

@@ -651,9 +651,13 @@ pub struct Worker {
     pub(crate) queue: JobQueue,
 }
 
+/// Describes the outcome of a call to [`Worker::yield_now`] or [`Worker::yield_local`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum Yield {
+    /// Indicates that a job was executed.
     Executed,
+    /// Indicates that no job was executed, and the worker should perhaps be put
+    /// to sleep.
     Idle,
 }
 
@@ -831,6 +835,9 @@ impl Worker {
 
     /// Cooperatively yields execution to the threadpool, allowing it to execute
     /// some work.
+    ///
+    /// This function only executes local work: work already queued on the
+    /// worker. It will never claim shaired work.
     #[inline]
     pub fn yield_local(&self) -> Yield {
         match self.queue.pop_back() {
@@ -844,6 +851,12 @@ impl Worker {
 
     /// Cooperatively yields execution to the threadpool, allowing it to execute
     /// some work.
+    ///
+    /// Tis function may execute either local or shared work: work already
+    /// queued on the worker, or work off-loaded by a different worker. If there
+    /// is no work on the pool, this will lock the thread-pool mutex, so it
+    /// should not be called within a hot loop. Consider using
+    /// [`Worker::yield_local`] instead.
     #[inline]
     pub fn yield_now(&self) -> Yield {
         match self.find_work() {