// file: crates/ksp-logging-lib/src/span.rs
// version: 2

/// KSP-owned handle to a tracing span.
#[derive(Clone, Debug)]
pub struct Span {
    inner: tracing::Span,
}

impl Span {
    /// Runs synchronous work while this span is entered.
    pub fn in_scope<T>(&self, operation: impl std::ops::FnOnce() -> T) -> T {
        return self.inner.in_scope(operation);
    }

    #[doc(hidden)]
    /// Constructs the KSP span wrapper for macro expansion support.
    #[must_use]
    pub fn __from_tracing(inner: tracing::Span) -> Self {
        return Self { inner };
    }

    /// Consumes this wrapper and returns the internal tracing span.
    pub(crate) fn into_tracing(self) -> tracing::Span {
        return self.inner;
    }
}

/// Instruments an asynchronous future with a KSP span.
///
/// The span is entered whenever the future is polled or dropped and exited when that operation returns, so no enter guard is held across an `.await` point.
pub fn instrument<F>(span: crate::Span, future: F) -> impl std::future::Future<Output = F::Output>
where
    F: std::future::Future,
{
    return tracing::Instrument::instrument(future, span.into_tracing());
}

#[cfg(test)]
#[path = "../unit_tests/span.rs"]
mod tests;