// Generated by Lisette bindgen
// Source: runtime/trace (Go stdlib)
// Go: 1.25.5
// Lisette: 0.1.14

import "go:context"
import "go:io"
import "go:time"

/// IsEnabled reports whether tracing is enabled.
/// The information is advisory only. The tracing status
/// may have changed by the time this function returns.
pub fn IsEnabled() -> bool

/// Log emits a one-off event with the given category and message.
/// Category can be empty and the API assumes there are only a handful of
/// unique categories in the system.
pub fn Log(ctx: context.Context, category: string, message: string)

/// Logf is like [Log], but the value is formatted using the specified format spec.
pub fn Logf(
  ctx: context.Context,
  category: string,
  format: string,
  args: VarArgs<Unknown>,
)

pub fn NewFlightRecorder(cfg: FlightRecorderConfig) -> Ref<FlightRecorder>

pub fn NewTask(pctx: context.Context, taskType: string) -> (context.Context, Ref<Task>)

/// Start enables tracing for the current program.
/// While tracing, the trace will be buffered and written to w.
/// Start returns an error if tracing is already enabled.
pub fn Start(w: io.Writer) -> Result<(), error>

pub fn StartRegion(ctx: context.Context, regionType: string) -> Ref<Region>

/// Stop stops the current tracing, if any.
/// Stop only returns after all the writes for the trace have completed.
pub fn Stop()

/// WithRegion starts a region associated with its calling goroutine, runs fn,
/// and then ends the region. If the context carries a task, the region is
/// associated with the task. Otherwise, the region is attached to the background
/// task.
/// 
/// The regionType is used to classify regions, so there should be only a
/// handful of unique region types.
pub fn WithRegion(ctx: context.Context, regionType: string, fn_: fn() -> ())

/// FlightRecorder represents a single consumer of a Go execution
/// trace.
/// It tracks a moving window over the execution trace produced by
/// the runtime, always containing the most recent trace data.
/// 
/// At most one flight recorder may be active at any given time,
/// though flight recording is allowed to be concurrently active
/// with a trace consumer using trace.Start.
/// This restriction of only a single flight recorder may be removed
/// in the future.
pub type FlightRecorder

pub struct FlightRecorderConfig {
  pub MinAge: time.Duration,
  pub MaxBytes: uint64,
}

/// Region is a region of code whose execution time interval is traced.
pub type Region

/// Task is a data type for tracing a user-defined, logical operation.
pub type Task

impl FlightRecorder {
  /// Enabled returns true if the flight recorder is active.
  /// Specifically, it will return true if Start did not return an error, and Stop has not yet been called.
  /// It is safe to call from multiple goroutines simultaneously.
  fn Enabled(self: Ref<FlightRecorder>) -> bool

  /// Start activates the flight recorder and begins recording trace data.
  /// Only one call to trace.Start may be active at any given time.
  /// In addition, currently only one flight recorder may be active in the program.
  /// Returns an error if the flight recorder cannot be started or is already started.
  fn Start(self: Ref<FlightRecorder>) -> Result<(), error>

  /// Stop ends recording of trace data. It blocks until any concurrent WriteTo calls complete.
  fn Stop(self: Ref<FlightRecorder>)

  /// WriteTo snapshots the moving window tracked by the flight recorder.
  /// The snapshot is expected to contain data that is up-to-date as of when WriteTo is called,
  /// though this is not a hard guarantee.
  /// Only one goroutine may execute WriteTo at a time.
  /// An error is returned upon failure to write to w, if another WriteTo call is already in-progress,
  /// or if the flight recorder is inactive.
  fn WriteTo(self: Ref<FlightRecorder>, w: io.Writer) -> Result<int64, error>
}

impl Region {
  /// End marks the end of the traced code region.
  fn End(self: Ref<Region>)
}

impl Task {
  /// End marks the end of the operation represented by the [Task].
  fn End(self: Ref<Task>)
}
