llam 0.1.4

Safe, Go-style Rust bindings for the LLAM runtime
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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

use crate::error::{Error, Result};
use crate::sys;
use crate::task::{self, JoinHandle, SpawnOptions};
use std::sync::Arc;

struct Inner {
    raw: *mut sys::llam_cancel_token_t,
}

unsafe impl Send for Inner {}
unsafe impl Sync for Inner {}

impl Drop for Inner {
    fn drop(&mut self) {
        if !self.raw.is_null() {
            unsafe {
                let _ = sys::llam_cancel_token_destroy(self.raw);
            }
        }
    }
}

#[derive(Clone)]
pub struct CancelToken {
    inner: Arc<Inner>,
}

impl CancelToken {
    pub fn new() -> Result<Self> {
        let raw = unsafe { sys::llam_cancel_token_create() };
        if raw.is_null() {
            Err(Error::last())
        } else {
            Ok(Self {
                inner: Arc::new(Inner { raw }),
            })
        }
    }

    pub fn cancel(&self) -> Result<()> {
        let rc = unsafe { sys::llam_cancel_token_cancel(self.inner.raw) };
        if rc == 0 {
            Ok(())
        } else {
            Err(Error::last())
        }
    }

    pub fn is_cancelled(&self) -> bool {
        unsafe { sys::llam_cancel_token_is_cancelled(self.inner.raw) != 0 }
    }

    pub(crate) fn raw(&self) -> *mut sys::llam_cancel_token_t {
        self.inner.raw
    }
}

/// Shared cancellation scope for tasks spawned with the same LLAM cancel token.
///
/// `CancelScope` is intentionally lightweight: it propagates cooperative
/// cancellation through a shared [`CancelToken`], but it does not join child
/// tasks on drop. Keep the returned [`JoinHandle`]s when completion matters.
pub struct CancelScope {
    token: CancelToken,
    cancel_on_drop: bool,
}

impl CancelScope {
    /// Create a scope that cancels its token when dropped.
    pub fn new() -> Result<Self> {
        Ok(Self {
            token: CancelToken::new()?,
            cancel_on_drop: true,
        })
    }

    /// Create a scope that does not cancel automatically on drop.
    pub fn detached() -> Result<Self> {
        Ok(Self {
            token: CancelToken::new()?,
            cancel_on_drop: false,
        })
    }

    /// Enable or disable cancellation when the scope is dropped.
    pub fn with_cancel_on_drop(mut self, enabled: bool) -> Self {
        self.cancel_on_drop = enabled;
        self
    }

    /// Return a clone of the scope's shared cancellation token.
    pub fn token(&self) -> CancelToken {
        self.token.clone()
    }

    /// Request cooperative cancellation for every task observing this scope.
    pub fn cancel(&self) -> Result<()> {
        self.token.cancel()
    }

    /// Return whether the scope token has been cancelled.
    pub fn is_cancelled(&self) -> bool {
        self.token.is_cancelled()
    }

    /// Spawn a task using the scope's cancellation token.
    pub fn try_spawn<F, T>(&self, f: F) -> Result<JoinHandle<T>>
    where
        F: FnOnce() -> T + Send + 'static,
        T: Send + 'static,
    {
        self.try_spawn_with(SpawnOptions::new(), f)
    }

    /// Spawn a task and panic if LLAM rejects the spawn.
    pub fn spawn<F, T>(&self, f: F) -> JoinHandle<T>
    where
        F: FnOnce() -> T + Send + 'static,
        T: Send + 'static,
    {
        self.try_spawn(f).expect("llam scoped task spawn failed")
    }

    /// Spawn a task with custom options and the scope's cancellation token.
    ///
    /// If `opts` already contains a cancellation token, the scope token wins.
    pub fn try_spawn_with<F, T>(&self, opts: SpawnOptions, f: F) -> Result<JoinHandle<T>>
    where
        F: FnOnce() -> T + Send + 'static,
        T: Send + 'static,
    {
        task::try_spawn_with(opts.cancel(self.token.clone()), f)
    }

    /// Spawn a task with custom options and panic if LLAM rejects the spawn.
    pub fn spawn_with<F, T>(&self, opts: SpawnOptions, f: F) -> JoinHandle<T>
    where
        F: FnOnce() -> T + Send + 'static,
        T: Send + 'static,
    {
        self.try_spawn_with(opts, f)
            .expect("llam scoped task spawn failed")
    }
}

impl Drop for CancelScope {
    fn drop(&mut self) {
        if self.cancel_on_drop {
            let _ = self.token.cancel();
        }
    }
}