Documentation
¶
Overview ¶
Package runtime provides small runtime-oriented helpers used by go-service.
The package is intentionally small and focused. It contains:
- strict helpers for startup/config paths (Must),
- panic recovery conversion helpers (ConvertRecover and ErrRecovered),
- build/runtime metadata helpers (Version),
- optional runtime tuning integration (RegisterMemLimit), and
- an Fx wiring module (Module) to register runtime integrations.
Error handling helpers ¶
Must is intended for code paths where failure is not meaningfully recoverable (for example, mandatory startup wiring). It panics when given a non-nil error and is commonly paired with constructors that already return an error.
ConvertRecover is intended to be used with `recover()` in deferred functions. It converts an arbitrary recovered value into an error, wrapping it with ErrRecovered to provide a consistent sentinel that can be detected via errors.Is. The original panic value is preserved in the returned error string and, when it is already an error, is wrapped so it remains available via errors.As.
Example:
func run() (err error) {
defer func() {
if v := recover(); v != nil {
err = runtime.ConvertRecover(v)
}
}()
// ...
return nil
}
Version reporting ¶
Version returns the build version of the running binary by reading build info via runtime/debug.ReadBuildInfo. When build info is unavailable, Version returns "development".
Note: the exact value depends on how the binary is built. For example, builds produced from a module may embed a semantic version, a VCS-derived version, or "(devel)" depending on tooling and flags.
Memory limit integration (GOMEMLIMIT) ¶
RegisterMemLimit integrates with the upstream automemlimit library to set Go's memory limit (GOMEMLIMIT) based on container/cgroup constraints. This is typically useful in containerized deployments where the Go runtime otherwise cannot infer an appropriate heap limit.
RegisterMemLimit is best-effort: it intentionally ignores returned values and errors, because failing to set a memory limit should not typically prevent a service from starting.
Dependency injection ¶
Module is an Fx module that registers RegisterMemLimit, allowing services that include the runtime module to apply the optional runtime tuning automatically.
Start with Must, ConvertRecover, Version, and Module.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrRecovered = errors.New("recovered")
ErrRecovered is a sentinel error used to mark errors produced by ConvertRecover.
ConvertRecover wraps arbitrary panic values into an error and includes ErrRecovered in the returned error chain so callers can detect recovered-panics with:
errors.Is(err, runtime.ErrRecovered) == true
When the recovered value is already an error, ConvertRecover wraps it so it remains accessible via errors.As.
var Module = di.Module( di.Register(RegisterMemLimit), )
Module wires runtime integrations into go.uber.org/fx.
Including this module in an Fx application enables optional runtime tuning provided by this package.
Currently, Module registers RegisterMemLimit, which attempts to configure Go's memory limit (GOMEMLIMIT) using the automemlimit library based on container/cgroup constraints.
Note: RegisterMemLimit is best-effort and intentionally ignores errors, so including this module will not fail application startup if a memory limit cannot be determined or applied.
Functions ¶
func ConvertRecover ¶
ConvertRecover converts a recovered panic value into an error wrapped with ErrRecovered.
This helper is intended to be used with recover() inside a deferred function:
func run() (err error) {
defer func() {
if v := recover(); v != nil {
err = runtime.ConvertRecover(v)
}
}()
// ...
return nil
}
The returned error always includes ErrRecovered in its chain. The recovered value is represented as:
func Must ¶
func Must(err error)
Must panics if err is non-nil.
Must is intended for code paths where an error is not meaningfully recoverable, such as mandatory startup/configuration wiring. It is commonly used to reduce boilerplate when a function returns (T, error) and failure should abort:
v, err := build() runtime.Must(err)
Note: Must does not attach additional context. If you need context, wrap the error before calling Must.
func RegisterMemLimit ¶
RegisterMemLimit configures Go's memory limit (GOMEMLIMIT) using automemlimit.
In containerized environments, the Go runtime may not automatically infer an appropriate memory limit from cgroup constraints. This helper delegates to the upstream automemlimit library to set a Go memory limit based on the detected container/cgroup memory limit.
The provided logger is passed through to automemlimit and may be used to emit diagnostic messages about detection and the chosen limit.
RegisterMemLimit is best-effort: any returned values and errors are intentionally ignored so that failure to set GOMEMLIMIT does not prevent a service from starting. If you need to enforce that a limit is set or handle errors, call the upstream automemlimit API directly.
func Version ¶
func Version() string
Version returns the build version of the running binary.
It reads build info via debug.ReadBuildInfo and returns the main module version when build info is available. The returned value is the build-info value as-is, including "(devel)" for local development builds. If build info is unavailable, Version returns "development".
Types ¶
This section is empty.
Source Files