Module logging 

LoggingResource — telemetry decorator for any DeviceMemoryResource.

Wraps an inner resource and records every allocate, deallocate, and reap_pending call (success and failure) into a LoggingSink. The decorator is fully transparent to allocator semantics: it forwards every method, never alters the inner result, and never panics or returns an error caused by the sink itself. Logging failure is recorded into a per-resource diagnostic counter (visible via LoggingResource::dropped_records) and otherwise silenced — losing a log line must not corrupt allocation correctness.

Sink design

LoggingSink is a tiny trait with a single emit method that returns Result<(), SinkError>. The default in-memory sink (InMemorySink) buffers records in a Mutex<Vec<LogRecord>> and is the test workhorse — it lets unit tests assert the exact sequence of records without filesystem dependencies. A future CsvFileSink or RingBufferSink slots in without touching the decorator.

Record contents

Every emitted LogRecord carries:

• action — Allocate / Deallocate / ReapPending
• device_ordinal
• stream_id — present for Allocate / Deallocate (the block’s alloc_stream); absent for ReapPending which spans streams.
• ptr / bytes / tag / generation — present when the operation has a corresponding DeviceBlock reference.
• thread_id — std::thread::current().id() rendered as u64 for portability.
• order_counter — monotonic per-process u64. Strictly increasing across all sinks, all threads, all resources.
• timestamp_nanos — SystemTime::now() since UNIX epoch in nanoseconds. Wall-clock; not monotonic. Use order_counter for ordering, timestamp_nanos for human-readable spans.
• result — Ok or short error tag string.

Decorator does NOT capture the inner resource’s pre-call state (e.g., bytes_outstanding before allocate) — that would require locking the inner resource an extra time and is not part of the v0.6 telemetry contract. Callers that need pre/post diffs read bytes_outstanding themselves.

Structs

InMemorySink

In-memory sink for tests and lightweight use. Records are appended to a Vec under a Mutex. snapshot returns a clone so consumers can inspect without holding the mutex.

LogRecord

A single allocation-log entry. Values are owned/Copy so the record is Clone + Send + Sync and trivially serializable.

LoggingResource

Telemetry decorator for DeviceMemoryResource.

NullSink

Discard sink: accepts every record and drops it. Use this when the test or production stack needs the runtime composition to match LoggingResource(...) shape but does not need to retain log records.

Enums

LogAction

Action recorded in a LogRecord. Distinct variants for the three inner methods so consumers can filter without parsing the result message.

LogResult

Result status as recorded in a log entry. Successful operations are recorded as Ok; failed ones carry the error variant tag plus an optional short message. We keep the message bounded so a runaway driver-error string cannot blow up the sink buffer.

SinkError

Sink-side error. Returned by LoggingSink::emit when the sink cannot accept a record (full ring buffer, IO error, etc.). The decorator catches this and increments LoggingResource::dropped_records; it does not propagate the error to the allocator caller.

Traits

LoggingSink

Trait for log destinations. Implementations are required to be thread-safe (Send + Sync); the decorator may emit from any thread that calls into the resource.