// Generated by Lisette bindgen
// Source: runtime/pprof (Go stdlib)
// Go: 1.25.10
// Lisette: 0.3.0

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

/// Do calls f with a copy of the parent context with the
/// given labels added to the parent's label map.
/// Goroutines spawned while executing f will inherit the augmented label-set.
/// Each key/value pair in labels is inserted into the label map in the
/// order provided, overriding any previous value for the same key.
/// The augmented label map will be set for the duration of the call to f
/// and restored once f returns.
pub fn Do(ctx: context.Context, labels: LabelSet, f: fn(context.Context) -> ())

/// ForLabels invokes f with each label set on the context.
/// The function f should return true to continue iteration or false to stop iteration early.
pub fn ForLabels(ctx: context.Context, f: fn(string, string) -> bool)

/// Label returns the value of the label with the given key on ctx, and a boolean indicating
/// whether that label exists.
pub fn Label(ctx: context.Context, key: string) -> Option<string>

/// Labels takes an even number of strings representing key-value pairs
/// and makes a [LabelSet] containing them.
/// A label overwrites a prior label with the same key.
/// Currently only the CPU and goroutine profiles utilize any labels
/// information.
/// See https://golang.org/issue/23458 for details.
pub fn Labels(args: VarArgs<string>) -> LabelSet

/// Lookup returns the profile with the given name, or nil if no such profile exists.
pub fn Lookup(name: string) -> Option<Ref<Profile>>

/// NewProfile creates a new profile with the given name.
/// If a profile with that name already exists, NewProfile panics.
/// The convention is to use a 'import/path.' prefix to create
/// separate name spaces for each package.
/// For compatibility with various tools that read pprof data,
/// profile names should not contain spaces.
pub fn NewProfile(name: string) -> Ref<Profile>

/// Profiles returns a slice of all the known profiles, sorted by name.
pub fn Profiles() -> Slice<Ref<Profile>>

/// SetGoroutineLabels sets the current goroutine's labels to match ctx.
/// A new goroutine inherits the labels of the goroutine that created it.
/// This is a lower-level API than [Do], which should be used instead when possible.
pub fn SetGoroutineLabels(ctx: context.Context)

/// StartCPUProfile enables CPU profiling for the current process.
/// While profiling, the profile will be buffered and written to w.
/// StartCPUProfile returns an error if profiling is already enabled.
/// 
/// On Unix-like systems, StartCPUProfile does not work by default for
/// Go code built with -buildmode=c-archive or -buildmode=c-shared.
/// StartCPUProfile relies on the SIGPROF signal, but that signal will
/// be delivered to the main program's SIGPROF signal handler (if any)
/// not to the one used by Go. To make it work, call [os/signal.Notify]
/// for [syscall.SIGPROF], but note that doing so may break any profiling
/// being done by the main program.
pub fn StartCPUProfile(w: io.Writer) -> Result<(), error>

/// StopCPUProfile stops the current CPU profile, if any.
/// StopCPUProfile only returns after all the writes for the
/// profile have completed.
pub fn StopCPUProfile()

/// WithLabels returns a new [context.Context] with the given labels added.
/// A label overwrites a prior label with the same key.
pub fn WithLabels(ctx: context.Context, labels: LabelSet) -> context.Context

/// WriteHeapProfile is shorthand for [Lookup]("heap").WriteTo(w, 0).
/// It is preserved for backwards compatibility.
pub fn WriteHeapProfile(w: io.Writer) -> Result<(), error>

/// LabelSet is a set of labels.
pub type LabelSet

/// A Profile is a collection of stack traces showing the call sequences
/// that led to instances of a particular event, such as allocation.
/// Packages can create and maintain their own profiles; the most common
/// use is for tracking resources that must be explicitly closed, such as files
/// or network connections.
/// 
/// A Profile's methods can be called from multiple goroutines simultaneously.
/// 
/// Each Profile has a unique name. A few profiles are predefined:
/// 
/// 	goroutine    - stack traces of all current goroutines
/// 	heap         - a sampling of memory allocations of live objects
/// 	allocs       - a sampling of all past memory allocations
/// 	threadcreate - stack traces that led to the creation of new OS threads
/// 	block        - stack traces that led to blocking on synchronization primitives
/// 	mutex        - stack traces of holders of contended mutexes
/// 
/// These predefined profiles maintain themselves and panic on an explicit
/// [Profile.Add] or [Profile.Remove] method call.
/// 
/// The CPU profile is not available as a Profile. It has a special API,
/// the [StartCPUProfile] and [StopCPUProfile] functions, because it streams
/// output to a writer during profiling.
/// 
/// # Heap profile
/// 
/// The heap profile reports statistics as of the most recently completed
/// garbage collection; it elides more recent allocation to avoid skewing
/// the profile away from live data and toward garbage.
/// If there has been no garbage collection at all, the heap profile reports
/// all known allocations. This exception helps mainly in programs running
/// without garbage collection enabled, usually for debugging purposes.
/// 
/// The heap profile tracks both the allocation sites for all live objects in
/// the application memory and for all objects allocated since the program start.
/// Pprof's -inuse_space, -inuse_objects, -alloc_space, and -alloc_objects
/// flags select which to display, defaulting to -inuse_space (live objects,
/// scaled by size).
/// 
/// # Allocs profile
/// 
/// The allocs profile is the same as the heap profile but changes the default
/// pprof display to -alloc_space, the total number of bytes allocated since
/// the program began (including garbage-collected bytes).
/// 
/// # Block profile
/// 
/// The block profile tracks time spent blocked on synchronization primitives,
/// such as [sync.Mutex], [sync.RWMutex], [sync.WaitGroup], [sync.Cond], and
/// channel send/receive/select.
/// 
/// Stack traces correspond to the location that blocked (for example,
/// [sync.Mutex.Lock]).
/// 
/// Sample values correspond to cumulative time spent blocked at that stack
/// trace, subject to time-based sampling specified by
/// [runtime.SetBlockProfileRate].
/// 
/// # Mutex profile
/// 
/// The mutex profile tracks contention on mutexes, such as [sync.Mutex],
/// [sync.RWMutex], and runtime-internal locks.
/// 
/// Stack traces correspond to the end of the critical section causing
/// contention. For example, a lock held for a long time while other goroutines
/// are waiting to acquire the lock will report contention when the lock is
/// finally unlocked (that is, at [sync.Mutex.Unlock]).
/// 
/// Sample values correspond to the approximate cumulative time other goroutines
/// spent blocked waiting for the lock, subject to event-based sampling
/// specified by [runtime.SetMutexProfileFraction]. For example, if a caller
/// holds a lock for 1s while 5 other goroutines are waiting for the entire
/// second to acquire the lock, its unlock call stack will report 5s of
/// contention.
pub type Profile

impl Profile {
  /// Add adds the current execution stack to the profile, associated with value.
  /// Add stores value in an internal map, so value must be suitable for use as
  /// a map key and will not be garbage collected until the corresponding
  /// call to [Profile.Remove]. Add panics if the profile already contains a stack for value.
  /// 
  /// The skip parameter has the same meaning as [runtime.Caller]'s skip
  /// and controls where the stack trace begins. Passing skip=0 begins the
  /// trace in the function calling Add. For example, given this
  /// execution stack:
  /// 
  /// 	Add
  /// 	called from rpc.NewClient
  /// 	called from mypkg.Run
  /// 	called from main.main
  /// 
  /// Passing skip=0 begins the stack trace at the call to Add inside rpc.NewClient.
  /// Passing skip=1 begins the stack trace at the call to NewClient inside mypkg.Run.
  fn Add(self: Ref<Profile>, value: Unknown, skip: int)

  /// Count returns the number of execution stacks currently in the profile.
  fn Count(self: Ref<Profile>) -> int

  /// Name returns this profile's name, which can be passed to [Lookup] to reobtain the profile.
  fn Name(self: Ref<Profile>) -> string

  /// Remove removes the execution stack associated with value from the profile.
  /// It is a no-op if the value is not in the profile.
  fn Remove(self: Ref<Profile>, value: Unknown)

  /// WriteTo writes a pprof-formatted snapshot of the profile to w.
  /// If a write to w returns an error, WriteTo returns that error.
  /// Otherwise, WriteTo returns nil.
  /// 
  /// The debug parameter enables additional output.
  /// Passing debug=0 writes the gzip-compressed protocol buffer described
  /// in https://github.com/google/pprof/tree/main/proto#overview.
  /// Passing debug=1 writes the legacy text format with comments
  /// translating addresses to function names and line numbers, so that a
  /// programmer can read the profile without tools.
  /// 
  /// The predefined profiles may assign meaning to other debug values;
  /// for example, when printing the "goroutine" profile, debug=2 means to
  /// print the goroutine stacks in the same form that a Go program uses
  /// when dying due to an unrecovered panic.
  fn WriteTo(self: Ref<Profile>, w: io.Writer, debug: int) -> Result<(), error>
}
