Documentation
¶
Overview ¶
Package clock provides an injectable time source.
A Clock reads the current time and starts timers. The clock in use travels in the context.Context, like the logger of package logging: WithClock stores a clock in a context and FromContext reads it back. A context without a clock uses the real clock, backed by package time.
Time-based combinators of fp-go read the clock from the context, among them Delay, Timer, WithTimeout and Retrying of context/readerioresult and package effect. Tests install the clock of package clock/testclock and advance it explicitly, so that code which waits for minutes runs in microseconds and without sleeping.
ctx := pair.Second(clock.WithClock(testclock.New(start))(context.Background())) now := clock.Now(ctx)
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsReal ¶
IsReal reports whether c is the clock returned by Real.
Combinators use it to keep the exact behaviour of package time and context, for example context.WithTimeout, when no other clock is installed.
Parameters:
- c: The clock to check
Returns:
- bool: true if c is the real clock
Example ¶
ExampleIsReal distinguishes the real clock from a test clock.
fmt.Println(clock.IsReal(testclock.New(start)))
Output: false
func Now ¶
Now returns the current time of the clock in a context.
Parameters:
- ctx: The context to read the clock from
Returns:
- time.Time: The current time of the clock
See Also:
- FromContext: Reads the clock from a context
Example ¶
ExampleNow reads the time of the clock in a context.
tc := testclock.New(start) ctx := pair.Second(clock.WithClock(tc)(context.Background())) tc.Advance(90 * time.Minute) fmt.Println(clock.Now(ctx).Format(time.Kitchen))
Output: 1:30AM
func NowIO ¶
NowIO returns an IO that reads the current time of a clock.
It feeds constructors that expect an IO[time.Time], such as those of the circuit breaker, from a Clock.
Parameters:
- c: The clock to read
Returns:
- io.IO[time.Time]: An IO that returns c.Now() each time it runs
Example ¶
ExampleNowIO feeds an IO[time.Time] from a clock.
now := clock.NowIO(testclock.New(start)) fmt.Println(now().Year())
Output: 2024
func Sleep ¶
Sleep waits for d on the clock in a context.
The wait honours the context: if the context is cancelled before or while waiting, Sleep returns immediately with the cancellation cause, context.Cause(ctx).
Parameters:
- ctx: The context that provides the clock and the cancellation
- d: The duration to wait
Returns:
- error: nil after d has elapsed, the cancellation cause otherwise
See Also:
- FromContext: Reads the clock from a context
Example ¶
ExampleSleep waits for an hour on a test clock without sleeping.
tc := testclock.New(start)
ctx := pair.Second(clock.WithClock(tc)(context.Background()))
done := make(chan error)
go func() { done <- clock.Sleep(ctx, time.Hour) }()
tc.BlockUntil(1)
tc.Advance(time.Hour)
fmt.Println(<-done, clock.Now(ctx).Format(time.Kitchen))
Output: <nil> 1:00AM
func WithClock ¶
WithClock returns a Kleisli arrow that stores a clock in a context.
The resulting pair contains a no-op cancel function and the new context, so that it can be used with the Local combinators, in the same way as logging.WithLogger.
Parameters:
- c: The clock to store in the context
Returns:
- pair.Kleisli[context.CancelFunc, context.Context, context.Context]: A function that adds the clock to a context
See Also:
- FromContext: Reads the clock back
Example ¶
ExampleWithClock installs a test clock in a context.
ctx := pair.Second(clock.WithClock(testclock.New(start))(context.Background())) fmt.Println(clock.Now(ctx).Format(time.RFC3339))
Output: 2024-01-01T00:00:00Z
Types ¶
type Clock ¶
type Clock interface {
// Now returns the current time of the clock.
Now() time.Time
// After returns a channel that receives the time once d has elapsed on the clock,
// and a function that stops the timer and releases its resources. The stop
// function reports whether it stopped the timer before it fired, like
// time.Timer.Stop.
After(d time.Duration) (<-chan time.Time, func() bool)
}
Clock is a source of time.
Code that reads the time or waits for a duration through a Clock can be tested with a test clock, which advances only when the test says so, instead of sleeping.
func FromContext ¶
FromContext returns the clock stored in a context, or the real clock if there is none.
Parameters:
- ctx: The context to read the clock from
Returns:
- Clock: The clock of the context, or Real()
See Also:
- WithClock: Stores a clock in a context
- Real: The fallback clock
Example ¶
ExampleFromContext reads the clock back from a context.
tc := testclock.New(start) ctx := pair.Second(clock.WithClock(tc)(context.Background())) fmt.Println(clock.FromContext(ctx) == clock.Clock(tc))
Output: true
func Real ¶
func Real() Clock
Real returns the clock backed by package time.
It is the clock that FromContext returns when the context carries no clock.
Returns:
- Clock: The real clock
See Also:
- FromContext: Reads the clock from a context
Example ¶
ExampleReal shows that a context without a clock uses the real clock.
package main
import (
"context"
"fmt"
"github.com/IBM/fp-go/v2/clock"
)
func main() {
fmt.Println(clock.IsReal(clock.Real()))
fmt.Println(clock.IsReal(clock.FromContext(context.Background())))
}
Output: true true
Source Files
Directories