libtime

README

libtime

Project Overview

Package libtime is a library which provides common time operations.

Getting Started

The oss.indeed.com/go/libtime module can be installed by running:

$ go get oss.indeed.com/go/libtime

Example usage:

c := libtime.SystemClock()

func foo(c libtime.Clock) {
    now := c.Now()
}

Asking Questions

For technical questions about libtime, just file an issue in the GitHub tracker.

For questions about Open Source in Indeed Engineering, send us an email at opensource@indeed.com

Contributing

We welcome contributions! Feel free to help make libtime better.

Process

• Open an issue and describe the desired feature / bug fix before making changes. It's useful to get a second pair of eyes before investing development effort.
• Make the change. If adding a new feature, remember to provide tests that demonstrate the new feature works, including any error paths. If contributing a bug fix, add tests that demonstrate the erroneous behavior is fixed.
• Open a pull request. Automated CI tests will run. If the tests fail, please make changes to fix the behavior, and repeat until the tests pass.
• Once everything looks good, one of the indeedeng members will review the PR and provide feedback.

Maintainers

The oss.indeed.com/go/libtime module is maintained by Indeed Engineering.

While we are always busy helping people get jobs, we will try to respond to GitHub issues, pull requests, and questions within a couple of business days.

Code of Conduct

oss.indeed.com/go/libtime is governed by the Contributer Covenant v1.4.1

For more information please contact opensource@indeed.com.

License

The oss.indeed.com/go/libtime module is open source under the BSD-3-Clause license.

Documentation

Index

• Constants
• func After(ctx context.Context, duration time.Duration) <-chan time.Time
• func DurationToMillis(d time.Duration) int64
• func FromMilliseconds(ms int64) time.Time
• func ToMilliseconds(t time.Time) int64
• type Clock
  • func SystemClock() Clock
• type Sleeper
  • func NewSleeper() Sleeper
• type StopTimerFunc
  • func SafeTimer(duration time.Duration) (*time.Timer, StopTimerFunc)

Constants

const (
	// ISO8601Micro is the default joda datetime print format, which is useful
	// when interacting with services written in Java.
	ISO8601Micro = `2006-01-02T15:04:05.000-07:00`
)

Many common formats can be found in go's time package, such as ANSIC and RFC, so check before adding any format to this file.

Additional formats are described here for convenience.

Functions

func After

func After(ctx context.Context, duration time.Duration) <-chan time.Time

After is a safer, but more expensive alternative to time.After.

After waits for the duration to elapse and then sends the current time on the returned channel. If the context gets canceled before the duration elapses, no message is sent on the returned channel.

The returned channel is never closed.

func DurationToMillis

func DurationToMillis(d time.Duration) int64

DurationToMillis returns d in terms of milliseconds.

func FromMilliseconds

func FromMilliseconds(ms int64) time.Time

FromMilliseconds converts time in milliseconds since epoch to time.Time

func ToMilliseconds

func ToMilliseconds(t time.Time) int64

ToMilliseconds returns time in milliseconds since epoch

Types

type Clock

type Clock interface {
	// Now is the time on this Clock.
	Now() time.Time

	// Since returns the size of the interval between the time.Time of Clock.Now
	// and the provided time.Time.
	Since(time.Time) time.Duration

	// SinceMS returns the same thing as Since, but converted to milliseconds.
	SinceMS(time.Time) int
}

Clock provides a mock-able interface of some of the standard library time package functions, like time.Now and time.Since. A default implementation is provided by SystemClock which defers to the time package functions.

func SystemClock

func SystemClock() Clock

SystemClock creates a Clock that is implemented by deferring to the standard library time package.

type Sleeper

type Sleeper interface {
	// Sleep for the specified amount of time.
	Sleep(time.Duration)
}

A Sleeper is a useful way for calling time.Sleep in a mockable way for tests.

func NewSleeper

func NewSleeper() Sleeper

NewSleeper creates a Sleeper that will actually call time.Sleep under the hood, causing the program to sleep.

type StopTimerFunc

type StopTimerFunc func() bool

StopTimerFunc is used to stop a time.Timer.

Calling StopTimerFunc prevents its time.Timer from firing. Returns true if the call stops the timer, false if the timer has already expired. or has been stopped.

https://pkg.go.dev/time#Timer.Stop

func SafeTimer

func SafeTimer(duration time.Duration) (*time.Timer, StopTimerFunc)

SafeTimer creates a time.Timer and a StopTimerFunc, forcing the caller to deal with the otherwise potential resource leak. Encourages safe use of a time.Timer in a select statement, but without the overhead of a context.Context.

Typical usage:

t, stop := libtime.SafeTimer(interval)
defer stop()
for {
  select {
    case <- t.C:
      foo()
    case <- otherC :
      return
  }
}

Does not panic if duration is <= 0, instead assuming the smallest positive value.