// Generated by Lisette bindgen
// Source: runtime/debug (Go stdlib)
// Go: 1.25.5
// Lisette: 0.1.11

import "go:os"
import "go:time"

/// FreeOSMemory forces a garbage collection followed by an
/// attempt to return as much memory to the operating system
/// as possible. (Even if this is not called, the runtime gradually
/// returns memory to the operating system in a background task.)
pub fn FreeOSMemory()

pub fn ParseBuildInfo(data: string) -> Result<Ref<BuildInfo>, error>

/// PrintStack prints to standard error the stack trace returned by runtime.Stack.
pub fn PrintStack()

#[go(comma_ok)]
pub fn ReadBuildInfo() -> Option<Ref<BuildInfo>>

/// ReadGCStats reads statistics about garbage collection into stats.
/// The number of entries in the pause history is system-dependent;
/// stats.Pause slice will be reused if large enough, reallocated otherwise.
/// ReadGCStats may use the full capacity of the stats.Pause slice.
/// If stats.PauseQuantiles is non-empty, ReadGCStats fills it with quantiles
/// summarizing the distribution of pause time. For example, if
/// len(stats.PauseQuantiles) is 5, it will be filled with the minimum,
/// 25%, 50%, 75%, and maximum pause times.
pub fn ReadGCStats(stats: Ref<GCStats>)

/// SetCrashOutput configures a single additional file where unhandled
/// panics and other fatal errors are printed, in addition to standard error.
/// There is only one additional file: calling SetCrashOutput again overrides
/// any earlier call.
/// SetCrashOutput duplicates f's file descriptor, so the caller may safely
/// close f as soon as SetCrashOutput returns.
/// To disable this additional crash output, call SetCrashOutput(nil).
/// If called concurrently with a crash, some in-progress output may be written
/// to the old file even after an overriding SetCrashOutput returns.
pub fn SetCrashOutput(f: Ref<os.File>, opts: CrashOptions) -> Result<(), error>

/// SetGCPercent sets the garbage collection target percentage:
/// a collection is triggered when the ratio of freshly allocated data
/// to live data remaining after the previous collection reaches this percentage.
/// SetGCPercent returns the previous setting.
/// The initial setting is the value of the GOGC environment variable
/// at startup, or 100 if the variable is not set.
/// This setting may be effectively reduced in order to maintain a memory
/// limit.
/// A negative percentage effectively disables garbage collection, unless
/// the memory limit is reached.
/// See SetMemoryLimit for more details.
pub fn SetGCPercent(percent: int) -> int

/// SetMaxStack sets the maximum amount of memory that
/// can be used by a single goroutine stack.
/// If any goroutine exceeds this limit while growing its stack,
/// the program crashes.
/// SetMaxStack returns the previous setting.
/// The initial setting is 1 GB on 64-bit systems, 250 MB on 32-bit systems.
/// There may be a system-imposed maximum stack limit regardless
/// of the value provided to SetMaxStack.
/// 
/// SetMaxStack is useful mainly for limiting the damage done by
/// goroutines that enter an infinite recursion. It only limits future
/// stack growth.
pub fn SetMaxStack(bytes: int) -> int

/// SetMaxThreads sets the maximum number of operating system
/// threads that the Go program can use. If it attempts to use more than
/// this many, the program crashes.
/// SetMaxThreads returns the previous setting.
/// The initial setting is 10,000 threads.
/// 
/// The limit controls the number of operating system threads, not the number
/// of goroutines. A Go program creates a new thread only when a goroutine
/// is ready to run but all the existing threads are blocked in system calls, cgo calls,
/// or are locked to other goroutines due to use of runtime.LockOSThread.
/// 
/// SetMaxThreads is useful mainly for limiting the damage done by
/// programs that create an unbounded number of threads. The idea is
/// to take down the program before it takes down the operating system.
pub fn SetMaxThreads(threads: int) -> int

/// SetMemoryLimit provides the runtime with a soft memory limit.
/// 
/// The runtime undertakes several processes to try to respect this
/// memory limit, including adjustments to the frequency of garbage
/// collections and returning memory to the underlying system more
/// aggressively. This limit will be respected even if GOGC=off (or,
/// if SetGCPercent(-1) is executed).
/// 
/// The input limit is provided as bytes, and includes all memory
/// mapped, managed, and not released by the Go runtime. Notably, it
/// does not account for space used by the Go binary and memory
/// external to Go, such as memory managed by the underlying system
/// on behalf of the process, or memory managed by non-Go code inside
/// the same process. Examples of excluded memory sources include: OS
/// kernel memory held on behalf of the process, memory allocated by
/// C code, and memory mapped by syscall.Mmap (because it is not
/// managed by the Go runtime).
/// 
/// More specifically, the following expression accurately reflects
/// the value the runtime attempts to maintain as the limit:
/// 
/// 	runtime.MemStats.Sys - runtime.MemStats.HeapReleased
/// 
/// or in terms of the runtime/metrics package:
/// 
/// 	/memory/classes/total:bytes - /memory/classes/heap/released:bytes
/// 
/// A zero limit or a limit that's lower than the amount of memory
/// used by the Go runtime may cause the garbage collector to run
/// nearly continuously. However, the application may still make
/// progress.
/// 
/// The memory limit is always respected by the Go runtime, so to
/// effectively disable this behavior, set the limit very high.
/// [math.MaxInt64] is the canonical value for disabling the limit,
/// but values much greater than the available memory on the underlying
/// system work just as well.
/// 
/// See https://go.dev/doc/gc-guide for a detailed guide explaining
/// the soft memory limit in more detail, as well as a variety of common
/// use-cases and scenarios.
/// 
/// The initial setting is math.MaxInt64 unless the GOMEMLIMIT
/// environment variable is set, in which case it provides the initial
/// setting. GOMEMLIMIT is a numeric value in bytes with an optional
/// unit suffix. The supported suffixes include B, KiB, MiB, GiB, and
/// TiB. These suffixes represent quantities of bytes as defined by
/// the IEC 80000-13 standard. That is, they are based on powers of
/// two: KiB means 2^10 bytes, MiB means 2^20 bytes, and so on.
/// 
/// SetMemoryLimit returns the previously set memory limit.
/// A negative input does not adjust the limit, and allows for
/// retrieval of the currently set memory limit.
pub fn SetMemoryLimit(limit: int64) -> int64

/// SetPanicOnFault controls the runtime's behavior when a program faults
/// at an unexpected (non-nil) address. Such faults are typically caused by
/// bugs such as runtime memory corruption, so the default response is to crash
/// the program. Programs working with memory-mapped files or unsafe
/// manipulation of memory may cause faults at non-nil addresses in less
/// dramatic situations; SetPanicOnFault allows such programs to request
/// that the runtime trigger only a panic, not a crash.
/// The runtime.Error that the runtime panics with may have an additional method:
/// 
/// 	Addr() uintptr
/// 
/// If that method exists, it returns the memory address which triggered the fault.
/// The results of Addr are best-effort and the veracity of the result
/// may depend on the platform.
/// SetPanicOnFault applies only to the current goroutine.
/// It returns the previous setting.
pub fn SetPanicOnFault(enabled: bool) -> bool

/// SetTraceback sets the amount of detail printed by the runtime in
/// the traceback it prints before exiting due to an unrecovered panic
/// or an internal runtime error.
/// The level argument takes the same values as the GOTRACEBACK
/// environment variable. For example, SetTraceback("all") ensure
/// that the program prints all goroutines when it crashes.
/// See the package runtime documentation for details.
/// If SetTraceback is called with a level lower than that of the
/// environment variable, the call is ignored.
pub fn SetTraceback(level: string)

/// Stack returns a formatted stack trace of the goroutine that calls it.
/// It calls [runtime.Stack] with a large enough buffer to capture the entire trace.
pub fn Stack() -> Slice<uint8>

/// WriteHeapDump writes a description of the heap and the objects in
/// it to the given file descriptor.
/// 
/// WriteHeapDump suspends the execution of all goroutines until the heap
/// dump is completely written.  Thus, the file descriptor must not be
/// connected to a pipe or socket whose other end is in the same Go
/// process; instead, use a temporary file or network socket.
/// 
/// The heap dump format is defined at https://golang.org/s/go15heapdump.
pub fn WriteHeapDump(fd: uint)

/// BuildInfo represents the build information read from a Go binary.
pub struct BuildInfo {
  pub GoVersion: string,
  pub Path: string,
  pub Main: Module,
  pub Deps: Slice<Option<Ref<Module>>>,
  pub Settings: Slice<BuildSetting>,
}

/// A BuildSetting is a key-value pair describing one setting that influenced a build.
/// 
/// Defined keys include:
/// 
///   - -buildmode: the buildmode flag used (typically "exe")
///   - -compiler: the compiler toolchain flag used (typically "gc")
///   - CGO_ENABLED: the effective CGO_ENABLED environment variable
///   - CGO_CFLAGS: the effective CGO_CFLAGS environment variable
///   - CGO_CPPFLAGS: the effective CGO_CPPFLAGS environment variable
///   - CGO_CXXFLAGS:  the effective CGO_CXXFLAGS environment variable
///   - CGO_LDFLAGS: the effective CGO_LDFLAGS environment variable
///   - DefaultGODEBUG: the effective GODEBUG settings
///   - GOARCH: the architecture target
///   - GOAMD64/GOARM/GO386/etc: the architecture feature level for GOARCH
///   - GOOS: the operating system target
///   - GOFIPS140: the frozen FIPS 140-3 module version, if any
///   - vcs: the version control system for the source tree where the build ran
///   - vcs.revision: the revision identifier for the current commit or checkout
///   - vcs.time: the modification time associated with vcs.revision, in RFC3339 format
///   - vcs.modified: true or false indicating whether the source tree had local modifications
pub struct BuildSetting {
  pub Key: string,
  pub Value: string,
}

/// CrashOptions provides options that control the formatting of the
/// fatal crash message.
pub type CrashOptions

/// GCStats collect information about recent garbage collections.
pub struct GCStats {
  pub LastGC: time.Time,
  pub NumGC: int64,
  pub PauseTotal: time.Duration,
  pub Pause: Slice<time.Duration>,
  pub PauseEnd: Slice<time.Time>,
  pub PauseQuantiles: Slice<time.Duration>,
}

/// A Module describes a single module included in a build.
pub struct Module {
  pub Path: string,
  pub Version: string,
  pub Sum: string,
  pub Replace: Option<Ref<Module>>,
}

impl BuildInfo {
  /// String returns a string representation of a [BuildInfo].
  fn String(self: Ref<BuildInfo>) -> string
}
