ptime

Documentation

Overview

Package parltime provides on-time timers, 64-bit epoch, formaatting and other time functions.

Index

• Constants
• func Date(year int, month int, day int, hour int, min int, sec int, nsec int, ...) (t time.Time, valid bool)
• func Date1k(year int, month int, day int, hour int, min int, sec int, nsec int, ...) (t time.Time, valid bool)
• func Duration(d time.Duration) (printableDuration string)
• func Duro(period time.Duration, atTime time.Time) (d time.Duration)
• func GetTimeString(wallTime *time.Time) (s string)
• func Ms(d time.Duration) string
• func Ns(t time.Time) string
• func NsLocal(t time.Time) string
• func OnTickerThread(callback func(at time.Time), period time.Duration, loc *time.Location, g Go)
• func OnTimer(period time.Duration, t ...time.Time) (timer *time.Timer)
• func ParseNs(timeString string) (t time.Time, err error)
• func ParseRfc3339nsz(timeString string) (t time.Time, err error)
• func ParseS(timeString string) (t time.Time, err error)
• func ParseTime(dateString string) (tm time.Time, err error)
• func Rfc3339(t time.Time) string
• func Rfc3339msz(t time.Time) (s string)
• func Rfc3339nsz(t time.Time) (s string)
• func Rfc3339sz(t time.Time) (s string)
• func Rfc3339usz(t time.Time) (s string)
• func S(t time.Time) string
• func SGreater(t1 time.Time, t2 time.Time) bool
• type Alert
  • func NewAlert(d time.Duration) (al *Alert)
  • func (al *Alert) Start()
  • func (al *Alert) Stop()
• type AverageInterval
  • func NewAverageInterval(index PeriodIndex) (ai *AverageInterval)
  • func (a *AverageInterval) Add(value float64)
  • func (a *AverageInterval) Aggregate(countp *uint64, floatp *float64)
  • func (a *AverageInterval) Index() (index PeriodIndex)
• type Averager
  • func NewAverager[T constraints.Integer]() (averager *Averager[T])
  • func NewAverager2[T constraints.Integer](period time.Duration, periodCount int) (averager *Averager[T])
  • func (a *Averager[T]) Add(value T, t ...time.Time)
  • func (a *Averager[T]) Average(t ...time.Time) (average float64, count uint64)
• type Averager3
  • func NewAverager3[T constraints.Integer]() (averager *Averager3[T])
  • func (av *Averager3[T]) Add(value T, t ...time.Time)
  • func (av *Averager3[T]) Status() (s string)
• type ClosingTicker
  • func NewClosingTicker(d time.Duration) (t *ClosingTicker)
  • func (t *ClosingTicker) GetError() (maxDuration time.Duration, err error)
  • func (t *ClosingTicker) Shutdown()
• type Epoch
  • func EpochNow(t ...time.Time) (epoch Epoch)
  • func (epoch Epoch) IsValid() (isValid bool)
  • func (epoch Epoch) Time() (t time.Time)
• type EpochValue
  • func (ev *EpochValue) Get() (epoch Epoch)
  • func (ev *EpochValue) Set(epoch Epoch) (oldEpoch Epoch)
  • func (ev *EpochValue) SetTime(t ...time.Time) (oldEpoch Epoch)
• type Go
• type InvokeOnTimer
  • func NewInvokeOnTimer(d time.Duration, errPanic error, elapsedFunc func(), ...) (timer *InvokeOnTimer)
  • func (t *InvokeOnTimer) Stop()
• type OnTicker
  • func NewOnTicker(period time.Duration, loc ...*time.Location) (onTicker *OnTicker)
  • func (o *OnTicker) Stop()
• type Period
  • func NewPeriod(interval time.Duration) (period *Period)
  • func (p *Period) Available(now PeriodIndex, cap int) (periods int)
  • func (p *Period) Index(t ...time.Time) (index PeriodIndex)
  • func (p *Period) Since(now, before PeriodIndex) (periods int)
  • func (p *Period) Sub(now PeriodIndex, n int) (periodIndex PeriodIndex)
• type PeriodIndex
• type ThreadSafeTimer
  • func NewThreadSafeTimer(defaultDuration ...time.Duration) (timer *ThreadSafeTimer)
  • func (t *ThreadSafeTimer) Reset(duration time.Duration)
  • func (t *ThreadSafeTimer) Stop() (wasRunning bool)

Constants

const (
	Date6 = "060102"
)

const (
	FractionScale = uint64(1) << 63
)

const (

	// RFC3339NanoSpace RFC3339 format, ns precision, space separator
	RFC3339NanoSpace string = "2006-01-02 15:04:05.999999999Z07:00"
)

Functions

func Date

func Date(year int, month int, day int, hour int, min int, sec int, nsec int, loc *time.Location) (t time.Time, valid bool)

ptime.Date is like time.Date with a flag valid that indicates whether the provided values represents a valid date. year is a 4-digit year, ie. 2022 is 2022. month 1–12, day 1–31, hour 0–23 minute 0-59, sec 0–59

func Date1k

func Date1k(year int, month int, day int, hour int, min int, sec int, nsec int, loc *time.Location) (t time.Time, valid bool)

ptime.Date is like time.Date with a flag valid that indicates whether the provided values represents a valid date. year is a 4-digit year, ie. 2022 is 2022. month 1–12, day 1–31, hour 0–23 minute 0-59, sec 0–59 A year below 1000 is not considered valid

func Duration

func Duration(d time.Duration) (printableDuration string)

Duration formats time.Duration to string with 2 digits precision or better.

• Duration is more readable than time.Duration.String() that has full ns precision.
• max precision is ns for < 10 µs
• min precision is day for >= 10 days
• units: ns µs ms s m h d “17h27m”
• subsecond digits are rounded with halfway-value rounded away from zero
• second and larger values is truncate

func Duro

func Duro(period time.Duration, atTime time.Time) (d time.Duration)

Duro returns the duration in nanoseconds until the next duration-multiple from zero time.

• The period starts from atTime
• time zone for multiple-calculation is defined by atTime, often time.Local
• time zone matters for 24 h or longer durations

func GetTimeString

func GetTimeString(wallTime *time.Time) (s string)

GetTimeString rfc 3339: email time format 2020-12-04 20:20:17-08:00

func Ms

func Ms(d time.Duration) string

Ms gets duration in milliseconds

func Ns

func Ns(t time.Time) string

Ns converts time to string with nanosecond accuracy and UTC location

func NsLocal

func NsLocal(t time.Time) string

NsLocal converts time to string with nanosecond accuracy and local time zone

func OnTickerThread

func OnTickerThread(callback func(at time.Time), period time.Duration, loc *time.Location, g Go)

OnTickerThread is a goroutine that invokes a callback periodically

• period must be greater than zero or panic
• loc is optional time zone, default time.Local, other time zone is time.UTC
• — time zone matters for periods longer than 1 hour or time-zone offiset minutes
• g can be nil, in which panics are echoed to standard error. The thread is then not awaitable or cancelable
• OnTickerThread is a time.Ticker using on-period multiples that invokes a callback periodically without further action
• OnTickerThread eliminates channel receive actions at the cost of an additional OnTickerThread thread
• a thread-less on-period ticker is OnTicker

func OnTimer

func OnTimer(period time.Duration, t ...time.Time) (timer *time.Timer)

OnTimer returns a time.Timer that waits until the next period-multiple since zero time.

• default starting time until the period multiple is now: time.Now(), optionally the absolute time t
• t contains time zone that matters for periods over 1 hour, typically this is time.Local
• the other time zone for Go is time.UTC
• period must be greater than zero or panic
• time.NewTimer does not offer the period calculation

func ParseNs

func ParseNs(timeString string) (t time.Time, err error)

ParseNs parses an RFC3339 time string with nanosecond accuracy

func ParseRfc3339nsz

func ParseRfc3339nsz(timeString string) (t time.Time, err error)

ParseRfc3339nsz parses a UTC time string at nanoseconds precision.

"2022-01-01T08:00:00.000000000Z"

func ParseS

func ParseS(timeString string) (t time.Time, err error)

ParseS parses an RFC3339 time string with nanosecond accuracy

func ParseTime

func ParseTime(dateString string) (tm time.Time, err error)

ParseTime parses output from Rfc3339

func Rfc3339

func Rfc3339(t time.Time) string

Rfc3339 converts local time to string with second precision and time offset: 2006-01-02 15:04:05-07:00

func Rfc3339msz

func Rfc3339msz(t time.Time) (s string)

Rfc3339msz prints a time using UTC and milliseconds precision.

"2022-01-01T08:00:00.000Z"

func Rfc3339nsz

func Rfc3339nsz(t time.Time) (s string)

Rfc3339nsz prints a time using UTC and nanoseconds precision.

"2022-01-01T08:00:00.000000000Z"

func Rfc3339sz

func Rfc3339sz(t time.Time) (s string)

Rfc3339sz prints a time using UTC and seconds precision.

"2022-01-01T08:00:00Z"

func Rfc3339usz

func Rfc3339usz(t time.Time) (s string)

Rfc3339usz prints a time using UTC and microseconds precision.

"2022-01-01T08:00:00.000000Z"

func S

func S(t time.Time) string

S converts time to string with second accuracy and UTC location

func SGreater

func SGreater(t1 time.Time, t2 time.Time) bool

SGreater compares two times first rouding to second

Types

type Alert

type Alert struct {
	time.Duration
	// Timer.C can be awaited for any trigging of the timer
	//	- Timer.C never closes and only sends a single value on trig
	//	- Timer is reinitialized on each Start invocation
	*time.Timer
	// Fired may be set to true by consumer on Timer.C trig
	//	- doing so saves a [time.Timer.Stop] invocation on next [Alert.Stop]
	// true if the timer trigged after the last Start invocation prior to any Stop invocation
	Fired bool
}

Alert impelments a renewable alert timer. not thread-safe

func NewAlert

func NewAlert(d time.Duration) (al *Alert)

NewAlert allocates a renewable alert time of specific duration

• Alert.Start initializes a new period regardless of state
• Alert.Stop releases resources regardless of state. Alert.Stop is idempotent
• if Alert.Start was invoked, a subsequent Alert.Stop is required to release resources
• after Start, [Alert.Timer.C] can be awaited for any trigging of the timer
• [Alert.Timer.C] never closes and only sends a single value on trig
• [Alert.Fired] is true if Start was invoked and the timer trigged prior to Stop

func (*Alert) Start

func (al *Alert) Start()

Start initializes a new alert period

• can be invoked at any time. Not thread-safe

func (*Alert) Stop

func (al *Alert) Stop()

Stop releases resources associated with this alert

• idempotent, can be invoked at any time. Not thread-safe

type AverageInterval

type AverageInterval struct {
	// contains filtered or unexported fields
}

AverageInterval is a container for the datapoint aggregate over a single period

func NewAverageInterval

func NewAverageInterval(index PeriodIndex) (ai *AverageInterval)

NewAverageInterval returns an avareging container for one averaging interval

func (*AverageInterval) Add

func (a *AverageInterval) Add(value float64)

Add adds a datapoint to the averager

• count of values incremented
• value added to total

func (*AverageInterval) Aggregate

func (a *AverageInterval) Aggregate(countp *uint64, floatp *float64)

Aggregate provides averaging content for calculating the average

func (*AverageInterval) Index

func (a *AverageInterval) Index() (index PeriodIndex)

type Averager

type Averager[T constraints.Integer] struct {
	// contains filtered or unexported fields
}

Averager is a container for averaging integer values providing perioding and history.

• maxCount is the maximum interval over which average is calculated
• average is the average value of provided datapoints during all periods
• because averaging is over 10 or many periods, the average will change slowly

func NewAverager

func NewAverager[T constraints.Integer]() (averager *Averager[T])

NewAverager returns an object that calculates average over a number of interval periods.

• interval-length is 1 s
• averaging over 10 intervals

func NewAverager2

func NewAverager2[T constraints.Integer](period time.Duration, periodCount int) (averager *Averager[T])

NewAverager2 returns an object that calculates average over a number of interval periods.

• period 0 means default 1 s interval-length
• periodCount 0 means averaging over 10 intervals

func (*Averager[T]) Add

func (a *Averager[T]) Add(value T, t ...time.Time)

Add adds a new value basis for averaging

• value is the sample value
• t is the sample time, default time.Now()

func (*Averager[T]) Average

func (a *Averager[T]) Average(t ...time.Time) (average float64, count uint64)

Average returns the average

• t is time, default time.Now()
• if sample count aggregated across the slice zero, average is zero
• count is number of values making up the average

type Averager3

type Averager3[T constraints.Integer] struct {
	Averager[T]
	// contains filtered or unexported fields
}

Averager3 is an average container with last, average and max values.

func NewAverager3

func NewAverager3[T constraints.Integer]() (averager *Averager3[T])

NewAverager3 returns an calculator for last, average and max values.

func (*Averager3[T]) Add

func (av *Averager3[T]) Add(value T, t ...time.Time)

Add updates last, average and max values

func (*Averager3[T]) Status

func (av *Averager3[T]) Status() (s string)

Status returns "[last]/[average]/[max]"

• if no values at all: "-/-/-"
• if no values avaiable to calculate average "1s/-/10s"

type ClosingTicker

type ClosingTicker struct {
	C           <-chan time.Time
	MaxDuration time.Duration // atomic int64
	// contains filtered or unexported fields
}

ClosingTicker is like time.Ticker but the channel C closes on shutdown. A closing channel is detectable by listening threads. If the computer is busy swapping, ticks will be lost. MaxDuration indicates the longest time observed between ticks. MaxDuration is normally 1 s

func NewClosingTicker

func NewClosingTicker(d time.Duration) (t *ClosingTicker)

NewClosingTicker returns a Ticker whose channel C closes on shutdown. A closing channel is detectable by a listening thread.

func (*ClosingTicker) GetError

func (t *ClosingTicker) GetError() (maxDuration time.Duration, err error)

func (*ClosingTicker) Shutdown

func (t *ClosingTicker) Shutdown()

Shutdown causes the channel C to close and resources to be released

type Epoch

type Epoch time.Duration

Epoch translates a time value to a 64-bit value that can be used atomically.

func EpochNow

func EpochNow(t ...time.Time) (epoch Epoch)

EpochNow translates a time value to a 64-bit value that can be used atomically.

func (Epoch) IsValid

func (epoch Epoch) IsValid() (isValid bool)

IsValid returns true if epoch is not zero-time, ie. Epoch(0) corredsponding to time.TIME{} and Time.IsZero

func (Epoch) Time

func (epoch Epoch) Time() (t time.Time)

Time returns the time.Time value corresponding to epoch

type EpochValue

type EpochValue Epoch

EpochValue is a timestamp with Thread-Safe atomic access.

func (*EpochValue) Get

func (ev *EpochValue) Get() (epoch Epoch)

Get returns the current Epoch value

• zero epoch is returned as zero-time Time.IsZero, time.Time{}
• to get time.Time: epochValue.Get().Time()
• to check if non-zero: epochValue.Get().IsValid()

func (*EpochValue) Set

func (ev *EpochValue) Set(epoch Epoch) (oldEpoch Epoch)

Set updates the Epoch value returning the old value

• 0 is the zero-value

func (*EpochValue) SetTime

func (ev *EpochValue) SetTime(t ...time.Time) (oldEpoch Epoch)

SetTime updates the Epoch value to a time.Time value returning the old Epoch value

• default time value is time.Now()
• time.IsZero or time.Time{} is the zero-value

type Go

type Go interface {
	Done(err *error)
	Context() (ctx context.Context)
}

type InvokeOnTimer

type InvokeOnTimer struct {
	// contains filtered or unexported fields
}

InvokeOnTimer implements a timeout action

func NewInvokeOnTimer

func NewInvokeOnTimer(d time.Duration, errPanic error, elapsedFunc func(), errorSink ...cyclebreaker.ErrorSink1) (timer *InvokeOnTimer)

NewInvokeOnTimer panics or invokes elapsedFunc if not reset within d

• default d 100 ms
• on timer expiry:
• — if errPanic is non-nil, process-terminating panic
• — if elapsedFunc is non-nil, it is invoked. Panics in elapsedFunc are recovered
• errPanic and elapsedFunc cannot both be nil
• each NewInvokeOnTimer launches a separate, blocked thread
• if errCh is present it should be a buffered channel receving a value on thread-exit that may be a panic from the thread. the thread should not have any panics but a panic may occur in elapsedFunc.
• if errCh is missing or nil, panic is echoed to stderr
• resources are released on:
• — Stop invocation
• — timer firing

func (*InvokeOnTimer) Stop

func (t *InvokeOnTimer) Stop()

Stop cancels the timer and releases resources

type OnTicker

type OnTicker struct {
	C <-chan time.Time // The channel on which the ticks are delivered.
	// contains filtered or unexported fields
}

OnTicker is a ticker triggering on period-multiples since zero time

• time.Ticker has a C field and Stop and Reset methods
• onTickerThread is launched in the new function
• — to avoid memory leaks, the thread cannot hold pointers to OnTicker
• — but the thread and OnTicker can both point to shared data onTick

func NewOnTicker

func NewOnTicker(period time.Duration, loc ...*time.Location) (onTicker *OnTicker)

NewOnTicker returns a ticker that ticks on period-multiples since zero time.

• loc is optional time zone, default time.Local, other time zone is time.UTC
• — time zone matters for periods longer than 1 hour or time-zone offiset minutes
• period must be greater than zero or panic
• OnTicker is a time.Ticker enhanced with on-period multiples

func (*OnTicker) Stop

func (o *OnTicker) Stop()

type Period

type Period struct {
	// contains filtered or unexported fields
}

Period provides real-time based fixed-length interval perioding ordered using a uint64 zero-based index.

• Period provides first period index and fractional usage of the first period

func NewPeriod

func NewPeriod(interval time.Duration) (period *Period)

NewPeriod returns a new numbered-interval sequence.

func (*Period) Available

func (p *Period) Available(now PeriodIndex, cap int) (periods int)

Available returns the correct number of slice entries to incldue now

• after the inital few periods, returns cap
• possible values 1… but no greater than cap
• now cannot be less than period0

func (*Period) Index

func (p *Period) Index(t ...time.Time) (index PeriodIndex)

Index returns the index number for the current period or the period at time t

• index is a number p.period0 or larger

func (*Period) Since

func (p *Period) Since(now, before PeriodIndex) (periods int)

Since returns the number of periods difference that now is greater than before

• periods is >= 0
• now and before must be at least p.period0
• before cannot be greater than now

func (*Period) Sub

func (p *Period) Sub(now PeriodIndex, n int) (periodIndex PeriodIndex)

Sub returns a past period index by n intervals

• periodIndex will not be less than p.period0
• now cannot be less than p.period0

type PeriodIndex

type PeriodIndex uint64

type ThreadSafeTimer

type ThreadSafeTimer struct {

	// the timer initially stopped
	*time.Timer
	// contains filtered or unexported fields
}

ThreadSafeTimer is a timer that can be Reset by multiple threads. Improvements:

• Stop and Reset are thread-safe
• Reset includes Stop in a fail-safe sequence and can be invoked at any time by any thread
• NewThreadSafeTimer has a defaultDuration of 1 second if argument is missing, zero or negative
• Reset also uses defaultDuration if argument is zero or negative
• fields and method signatures are identical to time.Timer
• ThreadSafeTimer may be copied or stored in slices or maps
• —
• cost: 1 sync.Mutex, 1 int64, 2 pointers, 2 allocations
• time.Timer public methods and fields: C Reset Stop
• time.Timer Reset must be in an uninterrupted Stop-drain-Reset sequence or memory leaks result

func NewThreadSafeTimer

func NewThreadSafeTimer(defaultDuration ...time.Duration) (timer *ThreadSafeTimer)

NewThreadSafeTimer returns a running timer with thread-safe Reset

• default defaultDuration is 1 second for defaultDuration missing, zero or negative
• defaultDuration is the default for Reset when Reset argument is zero or negative
• Reset can be invoked at any time without any precautions.
• — time.Timer.Reset has many conditions to avoid memory leaks
• Stop and Reset methods are thread-safe
• a timer must either expire or have Stop invoked to release resources
• if timer was created in same thread or obtained via synchronize before, read of field C is thread-safe

func (*ThreadSafeTimer) Reset

func (t *ThreadSafeTimer) Reset(duration time.Duration)

Reset is thread-safe timer reset

• has default duration for duration == 0
• works with concurrent channel read
• works with concurrent timer.Stop
• —
• thread-safety is obtained by making the Stop-drain-Reset sequence atomic
• unsynchronized Reset will cause memory leaks

func (*ThreadSafeTimer) Stop

func (t *ThreadSafeTimer) Stop() (wasRunning bool)

Stop prevents the Timer from firing