yash-executor 1.0.1

single-threaded concurrent task executor
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

// This file is part of yash, an extended POSIX shell.
// Copyright (C) 2024 WATANABE Yuki

//! Implementation of `Waker`
//!
//! This module provides a function to convert a `Task` into a `Waker`. The
//! `RawWaker`'s data pointer is a `Rc<Task>`, and the `RawWakerVTable` contains
//! functions to clone, wake, wake by reference, and drop the `Rc<Task>`.

use crate::Task;
use alloc::rc::Rc;
use core::task::{RawWaker, RawWakerVTable, Waker};

unsafe fn clone(data: *const ()) -> RawWaker {
    unsafe {
        Rc::<Task>::increment_strong_count(data.cast());
        RawWaker::new(data, VTABLE)
    }
}

unsafe fn wake(data: *const ()) {
    unsafe {
        Rc::<Task>::from_raw(data.cast()).wake();
    }
}

unsafe fn wake_by_ref(data: *const ()) {
    unsafe {
        Rc::<Task>::increment_strong_count(data.cast());
        Rc::<Task>::from_raw(data.cast()).wake();
    }
}

unsafe fn drop(data: *const ()) {
    unsafe {
        Rc::<Task>::decrement_strong_count(data.cast());
    }
}

const VTABLE: &RawWakerVTable = &RawWakerVTable::new(clone, wake, wake_by_ref, drop);

/// Converts a `Task` into a `Waker`.
///
/// When the returned `Waker` is woken, the task will be enqueued to be polled
/// by the executor.
#[must_use]
pub(crate) fn into_waker(task: Rc<Task>) -> Waker {
    let data = Rc::into_raw(task).cast();
    let raw_waker = RawWaker::new(data, VTABLE);
    unsafe { Waker::from_raw(raw_waker) }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Task;
    use alloc::boxed::Box;
    use alloc::rc::Weak;
    use core::cell::RefCell;

    fn dummy_task() -> Rc<Task<'static>> {
        Rc::new(Task {
            executor: Weak::new(),
            future: RefCell::new(Some(Box::pin(async { unreachable!() }))),
        })
    }

    #[test]
    fn clone_increments_strong_count() {
        let task = dummy_task();
        let waker = into_waker(Rc::clone(&task));
        assert_eq!(Rc::strong_count(&task), 2);

        let clone = waker.clone();
        assert_eq!(Rc::strong_count(&task), 3);

        core::mem::drop(clone);
        assert_eq!(Rc::strong_count(&task), 2);

        core::mem::drop(waker);
        assert_eq!(Rc::strong_count(&task), 1);
    }

    #[test]
    fn wake_consumes_one_ref() {
        let task = dummy_task();
        let waker = into_waker(Rc::clone(&task));
        assert_eq!(Rc::strong_count(&task), 2);

        waker.wake();

        assert_eq!(Rc::strong_count(&task), 1);
    }

    #[test]
    fn wake_by_ref_does_not_consume_ref() {
        let task = dummy_task();
        let waker = into_waker(Rc::clone(&task));
        assert_eq!(Rc::strong_count(&task), 2);

        waker.wake_by_ref();

        assert_eq!(Rc::strong_count(&task), 2);

        core::mem::drop(waker);
        assert_eq!(Rc::strong_count(&task), 1);
    }

    #[test]
    fn drop_decrements_strong_count() {
        let task = dummy_task();
        let waker = into_waker(Rc::clone(&task));
        assert_eq!(Rc::strong_count(&task), 2);

        core::mem::drop(waker);

        assert_eq!(Rc::strong_count(&task), 1);
    }
}