use serde::Serialize;
use std::cell::Cell;
use std::fs::File;
use std::io::{Seek, SeekFrom};
use std::marker::PhantomData;
use std::os::fd::AsRawFd;
use std::rc::Rc;
use std::sync::atomic::{AtomicU64, Ordering};
pub const MAGIC: [u8; 8] = *b"DCLPHEV1";
pub const SCHEMA_VERSION: u16 = 1;
pub const RECORD_SIZE: usize = 96;
pub const MAX_RECORDS: u64 = 16_384;
const EINTR_RETRIES: u32 = 3;
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[repr(u8)]
pub enum EventKind {
Header = 1,
Enter = 2,
Transition = 3,
End = 4,
Terminal = 5,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[repr(u8)]
pub enum Outcome {
None = 0,
Ok = 1,
Defer = 2,
Taint = 3,
Eval = 4,
Rejected = 5,
Incomplete = 6,
Unwound = 7,
Truncated = 8,
Abandoned = 9,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[repr(u8)]
pub enum RootKind {
Unknown = 0,
Expression = 1,
Document = 2,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
pub struct RootIdentity {
pub hash: u64,
pub utf8_len: u64,
pub kind: RootKind,
}
impl RootIdentity {
pub const NONE: Self = Self {
hash: 0,
utf8_len: 0,
kind: RootKind::Unknown,
};
pub fn new(name: &str, kind: RootKind) -> Self {
let mut hash = 14_695_981_039_346_656_037_u64;
for byte in name.bytes() {
hash ^= u64::from(byte);
hash = hash.wrapping_mul(1_099_511_628_211);
}
Self {
hash,
utf8_len: name.len() as u64,
kind,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[repr(u8)]
pub enum StopReason {
None = 0,
Cap = 1,
Clock = 2,
Write = 3,
ShortWrite = 4,
Interrupted = 5,
ScopeOrder = 6,
Reentrant = 7,
Abandoned = 8,
OpenScopes = 9,
CounterOverflow = 10,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
pub struct Status {
pub generation: u64,
pub max_records: u64,
pub records_written: u64,
pub bytes_written: u64,
pub last_sequence: u64,
pub last_monotonic_ns: u64,
pub enabled: bool,
pub terminal_written: bool,
pub open_scopes: u32,
pub stop_reason: StopReason,
pub errno: i32,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum InstallError {
InvalidLimit,
AlreadyInstalled,
Busy,
ThreadUnavailable,
NotEmptyRegularFile,
File(i32),
GenerationExhausted,
}
#[derive(Clone, Copy)]
struct Payload {
kind: EventKind,
outcome: Outcome,
stage: u32,
span: u64,
parent: u64,
ordinal: u64,
root: RootIdentity,
depth: u32,
}
#[derive(Clone, Copy)]
struct State {
fd: i32,
pid: u32,
status: Status,
next_span: u64,
current_span: u64,
}
struct Local {
state: Cell<Option<State>>,
busy: Cell<bool>,
reentered: Cell<bool>,
}
thread_local! {
static LOCAL: Local = const { Local {
state: Cell::new(None), busy: Cell::new(false), reentered: Cell::new(false),
} };
}
static NEXT_GENERATION: AtomicU64 = AtomicU64::new(1);
fn os_errno() -> i32 {
std::io::Error::last_os_error().raw_os_error().unwrap_or(0)
}
fn clock_ns() -> Result<u64, i32> {
#[cfg(test)]
if test_io::clock_fails() {
return Err(libc::EIO);
}
let mut ts = libc::timespec {
tv_sec: 0,
tv_nsec: 0,
};
if unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) } != 0 {
return Err(os_errno());
}
if ts.tv_sec < 0 || ts.tv_nsec < 0 || ts.tv_nsec >= 1_000_000_000 {
return Err(0);
}
(ts.tv_sec as u64)
.checked_mul(1_000_000_000)
.and_then(|v| v.checked_add(ts.tv_nsec as u64))
.ok_or(0)
}
fn write_record(fd: i32, record: &[u8; RECORD_SIZE]) -> Result<usize, i32> {
#[cfg(test)]
if let Some(result) = test_io::intercept(fd, record) {
return result;
}
let written = unsafe { libc::write(fd, record.as_ptr().cast(), RECORD_SIZE) };
if written < 0 {
Err(os_errno())
} else {
Ok(written as usize)
}
}
fn encode(state: &State, p: Payload, time: u64) -> [u8; RECORD_SIZE] {
let mut out = [0_u8; RECORD_SIZE];
out[..8].copy_from_slice(&MAGIC);
out[8..10].copy_from_slice(&SCHEMA_VERSION.to_le_bytes());
out[10] = p.kind as u8;
out[11] = p.outcome as u8;
out[12..16].copy_from_slice(&p.stage.to_le_bytes());
out[16..24].copy_from_slice(&(state.status.records_written + 1).to_le_bytes());
out[24..32].copy_from_slice(&time.to_le_bytes());
out[32..40].copy_from_slice(&p.span.to_le_bytes());
out[40..48].copy_from_slice(&p.parent.to_le_bytes());
out[48..56].copy_from_slice(&p.ordinal.to_le_bytes());
out[56..64].copy_from_slice(&p.root.hash.to_le_bytes());
out[64..72].copy_from_slice(&p.root.utf8_len.to_le_bytes());
out[72..80].copy_from_slice(&state.status.generation.to_le_bytes());
out[80..84].copy_from_slice(&state.pid.to_le_bytes());
out[84..88].copy_from_slice(&state.status.errno.to_le_bytes());
out[88] = p.root.kind as u8;
out[89] = state.status.stop_reason as u8;
out[92..96].copy_from_slice(&p.depth.to_le_bytes());
out
}
impl State {
fn stop(&mut self, reason: StopReason, errno: i32) {
if matches!(
self.status.stop_reason,
StopReason::None | StopReason::Cap | StopReason::Abandoned | StopReason::OpenScopes
) {
self.status.stop_reason = reason;
self.status.errno = errno;
}
self.status.enabled = false;
}
fn terminal(&self, outcome: Outcome) -> Payload {
Payload {
kind: EventKind::Terminal,
outcome,
stage: 0,
span: self.current_span,
parent: 0,
ordinal: 0,
root: RootIdentity::NONE,
depth: self.status.open_scopes,
}
}
fn publish(&mut self, payload: Payload) -> bool {
if !self.status.enabled {
return false;
}
if payload.kind != EventKind::Terminal
&& self.status.records_written >= self.status.max_records - 1
{
self.status.stop_reason = StopReason::Cap;
self.publish(self.terminal(Outcome::Truncated));
self.status.enabled = false;
return false;
}
if self.status.records_written >= self.status.max_records {
self.stop(StopReason::Cap, 0);
return false;
}
let time = match clock_ns() {
Ok(time) if time >= self.status.last_monotonic_ns => time,
Ok(_) => {
self.stop(StopReason::Clock, 0);
return false;
}
Err(errno) => {
self.stop(StopReason::Clock, errno);
return false;
}
};
let record = encode(self, payload, time);
let mut retries = 0;
loop {
match write_record(self.fd, &record) {
Ok(bytes) => {
self.status.bytes_written += bytes as u64;
if bytes != RECORD_SIZE {
self.stop(StopReason::ShortWrite, 0);
return false;
}
self.status.records_written += 1;
self.status.last_sequence = self.status.records_written;
self.status.last_monotonic_ns = time;
self.status.terminal_written = payload.kind == EventKind::Terminal;
if self.status.terminal_written {
self.status.enabled = false;
}
return true;
}
Err(errno) if errno == libc::EINTR && retries < EINTR_RETRIES => retries += 1,
Err(errno) => {
self.stop(
if errno == libc::EINTR {
StopReason::Interrupted
} else {
StopReason::Write
},
errno,
);
return false;
}
}
}
}
}
fn with_state<T>(generation: Option<u64>, f: impl FnOnce(&mut State) -> T) -> Option<T> {
LOCAL
.try_with(|local| {
if local.busy.replace(true) {
local.reentered.set(true);
return None;
}
let result = local.state.get().and_then(|mut state| {
if generation.is_some_and(|id| id != state.status.generation) {
return None;
}
let result = f(&mut state);
if local.reentered.replace(false) {
state.stop(StopReason::Reentrant, 0);
}
if local
.state
.get()
.is_some_and(|s| s.status.generation == state.status.generation)
{
local.state.set(Some(state));
}
Some(result)
});
local.busy.set(false);
result
})
.ok()
.flatten()
}
pub struct SinkGuard {
file: File,
generation: u64,
last_status: Cell<Status>,
attached: Cell<bool>,
thread_bound: PhantomData<Rc<()>>,
}
pub fn install(mut file: File, max_records: u64) -> Result<SinkGuard, InstallError> {
if !(2..=MAX_RECORDS).contains(&max_records) {
return Err(InstallError::InvalidLimit);
}
LOCAL
.try_with(|local| {
if local.busy.get() {
return Err(InstallError::Busy);
}
if local.state.get().is_some() {
return Err(InstallError::AlreadyInstalled);
}
let metadata = file
.metadata()
.map_err(|e| InstallError::File(e.raw_os_error().unwrap_or(0)))?;
if !metadata.is_file() || metadata.len() != 0 {
return Err(InstallError::NotEmptyRegularFile);
}
file.seek(SeekFrom::Start(0))
.map_err(|e| InstallError::File(e.raw_os_error().unwrap_or(0)))?;
let generation = NEXT_GENERATION
.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |v| v.checked_add(1))
.map_err(|_| InstallError::GenerationExhausted)?;
let status = Status {
generation,
max_records,
records_written: 0,
bytes_written: 0,
last_sequence: 0,
last_monotonic_ns: 0,
enabled: true,
terminal_written: false,
open_scopes: 0,
stop_reason: StopReason::None,
errno: 0,
};
let state = State {
fd: file.as_raw_fd(),
pid: std::process::id(),
status,
next_span: 1,
current_span: 0,
};
local.state.set(Some(state));
let guard = SinkGuard {
file,
generation,
last_status: Cell::new(status),
attached: Cell::new(true),
thread_bound: PhantomData,
};
with_state(Some(generation), |s| {
s.publish(Payload {
kind: EventKind::Header,
outcome: Outcome::None,
stage: 0,
span: 0,
parent: 0,
ordinal: max_records,
root: RootIdentity::NONE,
depth: 0,
})
});
Ok(guard)
})
.unwrap_or(Err(InstallError::ThreadUnavailable))
}
impl SinkGuard {
pub fn status(&self) -> Status {
if let Some(status) = with_state(Some(self.generation), |s| s.status) {
self.last_status.set(status);
}
self.last_status.get()
}
fn close(&self, explicit: bool) -> Status {
if self.attached.replace(false) {
with_state(Some(self.generation), |s| {
if s.status.enabled {
let outcome = if !explicit {
s.status.stop_reason = StopReason::Abandoned;
if std::thread::panicking() {
Outcome::Unwound
} else {
Outcome::Abandoned
}
} else if s.status.open_scopes != 0 {
s.status.stop_reason = StopReason::OpenScopes;
Outcome::Incomplete
} else {
Outcome::Ok
};
s.publish(s.terminal(outcome));
s.status.enabled = false;
}
self.last_status.set(s.status);
});
let _ = LOCAL.try_with(|local| {
if local
.state
.get()
.is_some_and(|s| s.status.generation == self.generation)
{
local.state.set(None);
}
});
}
self.last_status.get()
}
pub fn finish(self) -> Status {
self.close(true)
}
}
impl Drop for SinkGuard {
fn drop(&mut self) {
self.close(false);
let _ = &self.file;
}
}
pub struct EventScope {
generation: u64,
span: u64,
parent: u64,
ordinal: u64,
root: RootIdentity,
stage: Cell<u32>,
active: Cell<bool>,
thread_bound: PhantomData<Rc<()>>,
}
impl EventScope {
pub fn begin(stage: u32, ordinal: u64, root: RootIdentity) -> Self {
let ids = with_state(None, |s| {
if !s.status.enabled {
return None;
}
let Some(next_span) = s.next_span.checked_add(1) else {
s.stop(StopReason::CounterOverflow, 0);
return None;
};
let Some(depth) = s.status.open_scopes.checked_add(1) else {
s.stop(StopReason::CounterOverflow, 0);
return None;
};
let span = s.next_span;
let parent = s.current_span;
if !s.publish(Payload {
kind: EventKind::Enter,
outcome: Outcome::None,
stage,
span,
parent,
ordinal,
root,
depth,
}) {
return None;
}
s.next_span = next_span;
s.current_span = span;
s.status.open_scopes = depth;
Some((s.status.generation, span, parent))
})
.flatten();
let (generation, span, parent) = ids.unwrap_or((0, 0, 0));
Self {
generation,
span,
parent,
ordinal,
root,
stage: Cell::new(stage),
active: Cell::new(ids.is_some()),
thread_bound: PhantomData,
}
}
pub fn transition(&self, stage: u32) {
if !self.active.get() {
return;
}
let published = with_state(Some(self.generation), |s| {
if !s.status.enabled {
return false;
}
if s.current_span != self.span {
s.stop(StopReason::ScopeOrder, 0);
return false;
}
s.publish(self.payload(
EventKind::Transition,
Outcome::None,
stage,
s.status.open_scopes,
))
})
.unwrap_or(false);
if published {
self.stage.set(stage);
}
}
fn payload(&self, kind: EventKind, outcome: Outcome, stage: u32, depth: u32) -> Payload {
Payload {
kind,
outcome,
stage,
span: self.span,
parent: self.parent,
ordinal: self.ordinal,
root: self.root,
depth,
}
}
pub fn finish(&self, outcome: Outcome) {
if !self.active.replace(false) {
return;
}
with_state(Some(self.generation), |s| {
if !s.status.enabled {
return;
}
if s.current_span != self.span || s.status.open_scopes == 0 {
s.stop(StopReason::ScopeOrder, 0);
return;
}
let depth = s.status.open_scopes - 1;
if s.publish(self.payload(EventKind::End, outcome, self.stage.get(), depth)) {
s.current_span = self.parent;
s.status.open_scopes = depth;
}
});
}
}
impl Drop for EventScope {
fn drop(&mut self) {
self.finish(if std::thread::panicking() {
Outcome::Unwound
} else {
Outcome::Incomplete
});
}
}
#[cfg(test)]
#[path = "../tests/private/phase_events_test.rs"]
mod tests;
#[cfg(test)]
mod test_io {
use super::*;
#[derive(Clone, Copy)]
pub(super) enum Mode {
Real,
Short(usize),
Error(i32, u32),
Reenter,
}
thread_local! {
pub(super) static MODE: Cell<Mode> = const { Cell::new(Mode::Real) };
pub(super) static CLOCK_FAIL: Cell<bool> = const { Cell::new(false) };
}
pub(super) fn clock_fails() -> bool {
CLOCK_FAIL.get()
}
pub(super) fn intercept(fd: i32, record: &[u8; RECORD_SIZE]) -> Option<Result<usize, i32>> {
match MODE.get() {
Mode::Real => None,
Mode::Short(bytes) => {
MODE.set(Mode::Real);
let bytes = bytes.min(RECORD_SIZE - 1);
let n = unsafe { libc::write(fd, record.as_ptr().cast(), bytes) };
Some(if n < 0 {
Err(os_errno())
} else {
Ok(n as usize)
})
}
Mode::Error(errno, remaining) => {
MODE.set(if remaining <= 1 {
Mode::Real
} else {
Mode::Error(errno, remaining - 1)
});
Some(Err(errno))
}
Mode::Reenter => {
MODE.set(Mode::Real);
let _scope = EventScope::begin(999, 0, RootIdentity::NONE);
None
}
}
}
}