Skip to main content

mytheclipse_queue/
job.rs

1//! The `Job` type and its metadata.
2//!
3//! A minimal, dependency-free in-process job queue using `tokio::sync::mpsc`.
4
5use std::sync::atomic::{AtomicU64, Ordering};
6use std::sync::OnceLock;
7use std::time::{Duration, SystemTime};
8
9/// A unique identifier for a queued job.
10#[derive(Debug, Clone, PartialEq, Eq, Hash)]
11pub struct JobId(pub String);
12
13impl JobId {
14    /// Generates an id that is unique within this process and across restarts.
15    ///
16    /// The prefix is fixed once per process from the start instant and the pid,
17    /// so two runs never overlap; the suffix is a monotonic counter, so two jobs
18    /// in one run never collide. This replaces a random UUID: uniqueness is the
19    /// only property callers need, and a counter gets it without a random
20    /// source or a 36-byte string.
21    pub fn generate() -> Self {
22        static PREFIX: OnceLock<String> = OnceLock::new();
23        static COUNTER: AtomicU64 = AtomicU64::new(0);
24
25        let prefix = PREFIX.get_or_init(|| {
26            let nanos = SystemTime::now()
27                .duration_since(SystemTime::UNIX_EPOCH)
28                .unwrap_or_default()
29                .as_nanos() as u64;
30            let mut prefix = String::with_capacity(32);
31            push_hex(&mut prefix, nanos);
32            push_hex(&mut prefix, u64::from(std::process::id()));
33            prefix
34        });
35        let sequence = COUNTER.fetch_add(1, Ordering::Relaxed);
36
37        // Size the id up front: `format!` would start at capacity zero and
38        // reallocate twice on the way to ~40 bytes, which is most of what this
39        // function used to cost.
40        let mut id = String::with_capacity(prefix.len() + 17);
41        id.push_str(prefix);
42        id.push('-');
43        push_hex(&mut id, sequence);
44        Self(id)
45    }
46}
47
48/// Appends `value` as lowercase hex. Avoids the `fmt` machinery, which is
49/// measurably slower than 16 shifts for a value this short.
50fn push_hex(out: &mut String, value: u64) {
51    const DIGITS: &[u8; 16] = b"0123456789abcdef";
52
53    let mut buf = [0u8; 16];
54    let mut cursor = buf.len();
55    let mut rest = value;
56    loop {
57        cursor -= 1;
58        buf[cursor] = DIGITS[(rest & 0xf) as usize];
59        rest >>= 4;
60        if rest == 0 {
61            break;
62        }
63    }
64    out.push_str(std::str::from_utf8(&buf[cursor..]).expect("hex digits are ASCII"));
65}
66
67impl std::fmt::Display for JobId {
68    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
69        write!(f, "{}", self.0)
70    }
71}
72
73/// A unit of queued work.
74#[derive(Debug, Clone)]
75pub struct Job {
76    /// The unique ID of this job.
77    pub id: JobId,
78    /// The topic/queue name the job was delivered from.
79    pub topic: String,
80    /// The raw payload bytes.
81    pub payload: Vec<u8>,
82    /// How many times this job has been attempted (0 = first attempt).
83    pub attempt: u32,
84    /// When the job was first enqueued.
85    pub enqueued_at: SystemTime,
86    /// When the job was delivered to the worker (None if not yet delivered).
87    pub delivered_at: Option<SystemTime>,
88    /// Optional visibility timeout - after this the job becomes visible again.
89    pub visibility_timeout: Option<Duration>,
90}
91
92impl Job {
93    /// Builds a job on its first attempt.
94    ///
95    /// `delivered_at` stays `None` until a worker takes it.
96    pub fn new(id: JobId, topic: &str, payload: Vec<u8>) -> Self {
97        // One clock read for both timestamps: they describe the same instant,
98        // and `SystemTime::now()` is not free.
99        let now = SystemTime::now();
100        Self {
101            id,
102            topic: topic.to_string(),
103            payload,
104            attempt: 0,
105            enqueued_at: now,
106            delivered_at: Some(now),
107            visibility_timeout: None,
108        }
109    }
110}
111
112#[cfg(test)]
113mod tests {
114    use super::*;
115
116    #[test]
117    fn generated_ids_are_unique() {
118        let a = JobId::generate();
119        let b = JobId::generate();
120        assert_ne!(a, b);
121    }
122
123    #[test]
124    fn generated_ids_share_the_process_prefix() {
125        let a = JobId::generate().0;
126        let b = JobId::generate().0;
127        let prefix = |s: &str| s.rsplit_once('-').unwrap().0.to_owned();
128        assert_eq!(prefix(&a), prefix(&b));
129    }
130}