Documentation
¶
Overview ¶
Package value provides atomic numeric types and formatting utilities.
Atomic Values ¶
Three concrete atomic types wrap sync/atomic operations:
- AtomicInt64: thread-safe int64
- AtomicUint64: thread-safe uint64
- AtomicFloat64: thread-safe float64, using math.Float64bits/Float64frombits for lock-free CAS
All three implement io.WriterTo for zero-copy serialization.
var counter value.AtomicUint64 counter.Add(1) v := counter.Load()
Formatting ¶
AppendFloat64 formats float64 values to a byte buffer with special handling for +Inf, -Inf, and NaN as required by OpenMetrics.
AppendTimestamp formats time.Time as Unix seconds with nanosecond precision.
WriteTimestamp writes a formatted timestamp to an io.Writer using a pooled buffer.
Français ¶
Ce package fournit des types numériques atomiques et des utilitaires de formatage.
Trois types atomiques concrets (AtomicInt64, AtomicUint64, AtomicFloat64) encapsulent les opérations sync/atomic. Les atomics float64 utilisent math.Float64bits/Float64frombits pour un CAS sans lock. Tous implémentent io.WriterTo pour la sérialisation sans copie.
Les fonctions de formatage gèrent les cas spéciaux OpenMetrics (+Inf, -Inf, NaN) et les timestamps Unix avec précision nanoseconde.
Index ¶
- func AppendCanonicalFloat64(buf []byte, v float64) []byte
- func AppendFloat64(buf []byte, v float64) []byte
- func AppendTimestamp(buf []byte, t time.Time) []byte
- func WriteFloat64(w io.Writer, v float64) (int64, error)
- func WriteInt64(w io.Writer, v int64) (int64, error)
- func WriteTimestamp(w io.Writer, t time.Time) (int64, error)
- func WriteUint64(w io.Writer, v uint64) (int64, error)
- type AtomicFloat64
- type AtomicInt64
- type AtomicUint64
- type Number
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendCanonicalFloat64 ¶
AppendCanonicalFloat64 appends a float64 in OpenMetrics Canonical Number format. Integer-valued floats get a ".0" suffix (e.g. 1 → "1.0", 10 → "10.0"). This ensures labels like `le` and `quantile` are always unambiguously float.
func AppendFloat64 ¶
AppendFloat64 appends a float64 in OpenMetrics format to buf. Special values are formatted as: +Inf, -Inf, NaN
func AppendTimestamp ¶
AppendTimestamp appends a time.Time in OpenMetrics format (epoch.nanoseconds) to buf. For negative timestamps with positive nanoseconds (e.g., -0.5s = Unix(-1, 500000000)), the seconds and nanoseconds are adjusted so the decimal representation is correct: time.Unix(-1, 500000000) represents -0.5s, not -1.5s.
func WriteFloat64 ¶
WriteFloat64 writes a float64 value as a string to w. Special values are written as "+Inf", "-Inf", or "NaN" per OpenMetrics spec. Uses a pooled buffer for zero heap allocations in steady state.
func WriteInt64 ¶
WriteInt64 writes an int64 value as a decimal string to w. Uses a pooled buffer for zero heap allocations in steady state.
func WriteTimestamp ¶
WriteTimestamp writes a time.Time as Unix epoch seconds with nanosecond precision. Format: seconds.nnnnnnnnn (9 decimal places) Uses integer arithmetic to avoid float64 precision loss. Uses a pooled buffer for zero heap allocations in steady state. Delegates to AppendTimestamp for the formatting logic.
Types ¶
type AtomicFloat64 ¶
type AtomicFloat64 struct {
// contains filtered or unexported fields
}
AtomicFloat64 is a thread-safe float64 value with io.WriterTo support. Uses CAS loop for atomic Add operations.
func (*AtomicFloat64) Add ¶
func (a *AtomicFloat64) Add(delta float64) float64
Add atomically adds delta to the value and returns the new value. Uses a CAS loop because sync/atomic has no native float64 Add. No backoff is needed: the loop body is sub-nanosecond (bit conversion + addition), so a CAS failure means another goroutine just succeeded and the retry will almost certainly win on the next iteration. This is the standard Go pattern — the runtime itself uses identical unbounded CAS loops in sync/atomic internals.
func (*AtomicFloat64) Load ¶
func (a *AtomicFloat64) Load() float64
Load atomically loads and returns the value.
func (*AtomicFloat64) Store ¶
func (a *AtomicFloat64) Store(val float64)
Store atomically stores val.
type AtomicInt64 ¶
type AtomicInt64 struct {
// contains filtered or unexported fields
}
AtomicInt64 is a thread-safe int64 value with io.WriterTo support.
func (*AtomicInt64) Add ¶
func (a *AtomicInt64) Add(delta int64) int64
Add atomically adds delta to the value and returns the new value.
func (*AtomicInt64) Load ¶
func (a *AtomicInt64) Load() int64
Load atomically loads and returns the value.
type AtomicUint64 ¶
type AtomicUint64 struct {
// contains filtered or unexported fields
}
AtomicUint64 is a thread-safe uint64 value with io.WriterTo support.
func (*AtomicUint64) Add ¶
func (a *AtomicUint64) Add(delta uint64) uint64
Add atomically adds delta to the value and returns the new value.
func (*AtomicUint64) Load ¶
func (a *AtomicUint64) Load() uint64
Load atomically loads and returns the value.
Source Files