alloc_observe.Session

1/// Represents an installed observation interval, managing session duration2/// while borrowing caller-owned sink and context storage. Callers must ensure3/// sink and context storage remain allocated at stable memory addresses4/// throughout the session. The session must be explicitly terminated by calling5/// deinit exactly once, as no automatic teardown is performed on drop. In6/// disabled builds, the session is inert. Callers must serialize session7/// lifecycle transitions externally, because the protocol does not support8/// overlapping the shutdown of an old session with the installation of a new9/// one.10pub const Session = struct {11    sink: if (enabled) ?*const Sink else void =12        if (enabled) null else {},13    active: if (enabled) bool else void =14        if (enabled) false else {},15    producer_id_floor: if (enabled) u64 else void =16        if (enabled) 0 else {},1718    /// Terminates an active session by unregistering the sink and spinning19    /// until the shared count of active spans and contexts drains to zero. The20    /// spin loop contains no timeout or cancellation path, requiring all21    /// concurrent operations to finish. Callers must invoke deinit outside22    /// callbacks and outside active suppression scopes (which trigger23    /// assertions if violated), and must ensure no outstanding spans or24    /// contexts remain open on the calling thread, or shutdown will spin25    /// indefinitely. Callers must also avoid holding locks required by26    /// in-flight callbacks. `Sink` memory and callback context pointers must27    /// remain valid and stable until this function returns. An enabled session28    /// must be deinitialized exactly once. In disabled builds, this call is an29    /// inert no-op.30    pub fn deinit(self: *Session) void {31        if (comptime !enabled) return;32        std.debug.assert(callback_depth == 0);33        std.debug.assert(self.active);34        const sink = self.sink.?;35        const address = @intFromPtr(sink);36        const previous = active_sink.cmpxchgStrong(37            address,38            0,39            .acq_rel,40            .acquire,41        );42        std.debug.assert(previous == null);43        while (active_operations.load(.acquire) != 0) {44            std.atomic.spinLoopHint();45        }46        self.active = false;47        self.sink = null;48    }4950    /// Reports the next producer identifier captured during session51    /// installation under the registry lock, or zero when observation is52    /// disabled. This boundary value separates producers registered prior to53    /// installation from those registered subsequently. Falling at or above54    /// this threshold indicates registration after the session began, but does55    /// not prove that an emitter event history is complete, because thread56    /// suppression or incomplete sink coverage may have omitted events.57    pub fn producerIdFloor(self: *const Session) u64 {58        if (comptime !enabled) return 0;59        return self.producer_id_floor;60    }61};

1/// Represents an installed observation interval, managing session duration2/// while borrowing caller-owned sink and context storage. Callers must ensure3/// sink and context storage remain allocated at stable memory addresses4/// throughout the session. The session must be explicitly terminated by calling5/// deinit exactly once, as no automatic teardown is performed on drop. In6/// disabled builds, the session is inert. Callers must serialize session7/// lifecycle transitions externally, because the protocol does not support8/// overlapping the shutdown of an old session with the installation of a new9/// one.10pub const Session = protocol.Session;