Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 1 | /// Set if the task is scheduled for running. |
| 2 | /// |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 3 | /// A task is considered to be scheduled whenever its `Task` reference exists. It therefore also |
| 4 | /// begins in scheduled state at the moment of creation. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 5 | /// |
| 6 | /// This flag can't be set when the task is completed. However, it can be set while the task is |
| 7 | /// running, in which case it will be rescheduled as soon as polling finishes. |
| 8 | pub(crate) const SCHEDULED: usize = 1 << 0; |
| 9 | |
| 10 | /// Set if the task is running. |
| 11 | /// |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 12 | /// A task is in running state while its future is being polled. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 13 | /// |
| 14 | /// This flag can't be set when the task is completed. However, it can be in scheduled state while |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 15 | /// it is running, in which case it will be rescheduled as soon as polling finishes. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 16 | pub(crate) const RUNNING: usize = 1 << 1; |
| 17 | |
| 18 | /// Set if the task has been completed. |
| 19 | /// |
| 20 | /// This flag is set when polling returns `Poll::Ready`. The output of the future is then stored |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 21 | /// inside the task until it becomes closed. In fact, `JoinHandle` picks up the output by marking |
| 22 | /// the task as closed. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 23 | /// |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 24 | /// This flag can't be set when the task is scheduled or running. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 25 | pub(crate) const COMPLETED: usize = 1 << 2; |
| 26 | |
| 27 | /// Set if the task is closed. |
| 28 | /// |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 29 | /// If a task is closed, that means it's either cancelled or its output has been consumed by the |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 30 | /// `JoinHandle`. A task becomes closed when: |
| 31 | /// |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 32 | /// 1. It gets cancelled by `Task::cancel()`, `Task::drop()`, or `JoinHandle::cancel()`. |
| 33 | /// 2. Its output gets awaited by the `JoinHandle`. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 34 | /// 3. It panics while polling the future. |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 35 | /// 4. It is completed and the `JoinHandle` gets dropped. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 36 | pub(crate) const CLOSED: usize = 1 << 3; |
| 37 | |
| 38 | /// Set if the `JoinHandle` still exists. |
| 39 | /// |
| 40 | /// The `JoinHandle` is a special case in that it is only tracked by this flag, while all other |
| 41 | /// task references (`Task` and `Waker`s) are tracked by the reference count. |
| 42 | pub(crate) const HANDLE: usize = 1 << 4; |
| 43 | |
| 44 | /// Set if the `JoinHandle` is awaiting the output. |
| 45 | /// |
| 46 | /// This flag is set while there is a registered awaiter of type `Waker` inside the task. When the |
| 47 | /// task gets closed or completed, we need to wake the awaiter. This flag can be used as a fast |
| 48 | /// check that tells us if we need to wake anyone without acquiring the lock inside the task. |
| 49 | pub(crate) const AWAITER: usize = 1 << 5; |
| 50 | |
| 51 | /// Set if the awaiter is locked. |
| 52 | /// |
Stjepan Glavina | 5c398cf | 2019-08-20 15:29:43 +0200 | [diff] [blame] | 53 | /// This lock is acquired before a new awaiter is registered or the existing one is woken up. |
Stjepan Glavina | 1479e86 | 2019-08-12 20:18:51 +0200 | [diff] [blame] | 54 | pub(crate) const LOCKED: usize = 1 << 6; |
| 55 | |
| 56 | /// A single reference. |
| 57 | /// |
| 58 | /// The lower bits in the state contain various flags representing the task state, while the upper |
| 59 | /// bits contain the reference count. The value of `REFERENCE` represents a single reference in the |
| 60 | /// total reference count. |
| 61 | /// |
| 62 | /// Note that the reference counter only tracks the `Task` and `Waker`s. The `JoinHandle` is |
| 63 | /// tracked separately by the `HANDLE` flag. |
| 64 | pub(crate) const REFERENCE: usize = 1 << 7; |