diff --git a/core/docs/en/ordered-work-steal.md b/core/docs/en/ordered-work-steal.md new file mode 100644 index 00000000..95b973e7 --- /dev/null +++ b/core/docs/en/ordered-work-steal.md @@ -0,0 +1,59 @@ +--- +title: Ordered Work Steal Overview +date: 2025-01-17 08:34:00 +author: loongs-zhang +--- + +# Ordered Work Steal Overview + +## Why ordered work steal? + +In the real world, there are always threads that complete their own tasks first, while other threads have tasks to be +processed. Then, a spectacular scene emerged where one core was in difficulty and other cores were watching. + +
+ +
+ +Obviously, we don't want this to happen. For idle threads, instead of letting them watch other threads working, it's +better to let them help other threads work. In addition, we hope to pop tasks based on priority, the higher the +priority, the earlier it will be popped up. + +## What is ordered work steal queue? + +An ordered work steal queue consists of a global queue and multiple local queues, the global queue is unbounded, while +the local queue has a bounded SkipList with collections. To ensure high performance, the number of local queues is +usually equal to the number of threads. + +## How `push` works + +```mermaid +flowchart TD + Cond{Is the local queue full?} + PS[Push to the local queue] + PTG[Push half of the low priority tasks from the local queue to the global queue] + PG[Push to the global queue] + push --> Cond + Cond -- No --> PS + Cond -- Yes --> PTG --- PG + +``` + +## How `pop` works + +```mermaid +flowchart TD + Cond1{Are there any tasks in the local queue?} + Cond2{Are there any tasks in other local queues?} + Cond3{Are there any tasks in the global queue?} + PS[Pop the task with the highest priority] + ST[Steal tasks with high priority from other local queues] + PF[Task not found] + pop --> Cond1 + Cond1 -- Yes --> PS + Cond1 -- No --> Cond2 + Cond2 -- Yes --> ST --> PS + Cond2 -- No --> Cond3 + Cond3 -- Yes --> PS + Cond3 -- No --> PF +``` diff --git a/core/docs/en/work-steal.md b/core/docs/en/work-steal.md new file mode 100644 index 00000000..96281690 --- /dev/null +++ b/core/docs/en/work-steal.md @@ -0,0 +1,58 @@ +--- +title: Work Steal Overview +date: 2025-01-17 08:34:00 +author: loongs-zhang +--- + +# Work Steal Overview + +## Why work steal? + +In the real world, there are always threads that complete their own tasks first, while other threads have tasks to be +processed. Then, a spectacular scene emerged where one core was in difficulty and other cores were watching. + +
+ +
+ +Obviously, we don't want this to happen. For idle threads, instead of letting them watch other threads working, it's +better to let them help other threads work. + +## What is work steal queue? + +A work steal queue consists of a global queue and multiple local queues, the global queue is unbounded, while the local +queue has a bounded RingBuffer. To ensure high performance, the number of local queues is usually equal to the number of +threads. + +## How `push` works + +```mermaid +flowchart TD + Cond{Is the local queue full?} + PS[Push to the local queue] + PTG[Push half of the tasks from the local queue to the global queue] + PG[Push to the global queue] + push --> Cond + Cond -- No --> PS + Cond -- Yes --> PTG --- PG + +``` + +## How `pop` works + +```mermaid +flowchart TD + Cond1{Are there any tasks in the local queue?} + Cond2{Are there any tasks in other local queues?} + Cond3{Are there any tasks in the global queue?} + PS[Pop a stack] + ST[Steal tasks from other local queues] + PF[Task not found] + pop --> Cond1 + Cond1 -- Yes --> PS + Cond1 -- No --> Cond2 + Cond2 -- Yes --> ST --> PS + Cond2 -- No --> Cond3 + Cond3 -- Yes --> PS + Cond3 -- No --> PF +``` diff --git a/core/src/common/mod.rs b/core/src/common/mod.rs index f92e005f..c37551fd 100644 --- a/core/src/common/mod.rs +++ b/core/src/common/mod.rs @@ -51,6 +51,7 @@ pub mod beans; /// assert_eq!(queue.pop(), None); /// ``` /// +#[doc = include_str!("../../docs/en/work-steal.md")] pub mod work_steal; /// Suppose a thread in a work-stealing scheduler is idle and looking for the next task to run. To @@ -87,6 +88,7 @@ pub mod work_steal; /// assert_eq!(queue.pop(), None); /// ``` /// +#[doc = include_str!("../../docs/en/ordered-work-steal.md")] pub mod ordered_work_steal; #[cfg(target_os = "linux")] diff --git a/docs/img/watching.png b/docs/img/watching.png new file mode 100644 index 00000000..f5f44caf Binary files /dev/null and b/docs/img/watching.png differ