API Reference

Complete documentation of clockz interfaces and implementations.

Clock Interface

The core interface implemented by both RealClock and FakeClock:

type Clock interface {
    Now() time.Time
    After(d time.Duration) <-chan time.Time
    AfterFunc(d time.Duration, f func()) Timer
    NewTimer(d time.Duration) Timer
    NewTicker(d time.Duration) Ticker
    Sleep(d time.Duration)
    Since(t time.Time) time.Duration
    WithTimeout(ctx context.Context, timeout time.Duration) (context.Context, context.CancelFunc)
    WithDeadline(ctx context.Context, deadline time.Time) (context.Context, context.CancelFunc)
}

Clock.Now

Now() time.Time

Returns the current time according to the clock.

• RealClock: Returns time.Now()
• FakeClock: Returns the fake clock's current time

Clock.After

After(d time.Duration) <-chan time.Time

Returns a channel that sends the current time after duration d.

• RealClock: Wraps time.After(d)
• FakeClock: Fires when fake time advances past target
• Channel has buffer of 1 to prevent blocking

Clock.AfterFunc

AfterFunc(d time.Duration, f func()) Timer

Executes function f after duration d.

• RealClock: Wraps time.AfterFunc(d, f), function runs in its own goroutine
• FakeClock: Executes synchronously when time advances
• Returns Timer that can be stopped or reset

Clock.NewTimer

NewTimer(d time.Duration) Timer

Creates a new Timer that fires after duration d.

• RealClock: Wraps time.NewTimer(d)
• FakeClock: Creates timer that respects fake time
• Timer can be stopped or reset
• Use timer.C() to access the channel

Clock.NewTicker

NewTicker(d time.Duration) Ticker

Creates a new Ticker that fires repeatedly every duration d.

• RealClock: Wraps time.NewTicker(d)
• FakeClock: Creates ticker that respects fake time
• Must call ticker.Stop() to release resources
• Panics if d <= 0 (both implementations)

Clock.Sleep

Sleep(d time.Duration)

Blocks the calling goroutine for duration d.

• RealClock: Wraps time.Sleep(d)
• FakeClock: Blocks until fake time advances by d

Clock.Since

Since(t time.Time) time.Duration

Returns time elapsed since t.

• Equivalent to clock.Now().Sub(t)

Clock.WithTimeout

WithTimeout(ctx context.Context, timeout time.Duration) (context.Context, context.CancelFunc)

Creates a context that cancels after timeout duration.

• RealClock: Wraps context.WithTimeout(ctx, timeout)
• FakeClock: Cancels when fake time advances past deadline
• Cancel function must be called to release resources

Clock.WithDeadline

WithDeadline(ctx context.Context, deadline time.Time) (context.Context, context.CancelFunc)

Creates a context that cancels at deadline time.

• RealClock: Wraps context.WithDeadline(ctx, deadline)
• FakeClock: Cancels when fake time reaches deadline
• Returns immediately cancelled context if deadline already passed
• Cancel function must be called to release resources

Timer Interface

type Timer interface {
    Stop() bool
    Reset(d time.Duration) bool
    C() <-chan time.Time
}

Timer.Stop

Stop() bool

Stops the timer from firing.

• Returns true if timer was stopped before firing
• Returns false if timer already fired or was stopped
• Safe to call multiple times

Timer.Reset

Reset(d time.Duration) bool

Resets the timer to fire after duration d.

• Returns true if timer was active before reset
• Returns false if timer had expired or was stopped
• Resets from current clock time, not original start time

Timer.C

C() <-chan time.Time

Returns the channel on which the timer sends its time.

• Channel has buffer of 1
• Receives exactly once when timer fires
• Channel is not closed after firing

Ticker Interface

type Ticker interface {
    Stop()
    C() <-chan time.Time
}

Ticker.Stop

Stop()

Stops the ticker.

• No more ticks sent after Stop
• Does not close the channel
• Required to release ticker resources

Ticker.C

C() <-chan time.Time

Returns the channel on which ticks are delivered.

• Channel has buffer of 1
• Sends time at regular intervals
• May drop ticks if receiver is slow

RealClock

var RealClock Clock = &realClock{}

Package-level variable that delegates to the standard time package.

Usage:

now := clockz.RealClock.Now()
timer := clockz.RealClock.NewTimer(5 * time.Second)

Characteristics:

• Thread-safe
• Zero overhead (direct delegation)
• No additional methods beyond Clock interface

FakeClock

Constructors

func NewFakeClock() *FakeClock

Creates a fake clock initialized to time.Now().

func NewFakeClockAt(t time.Time) *FakeClock

Creates a fake clock initialized to specific time t.

FakeClock.Advance

func (f *FakeClock) Advance(d time.Duration)

Advances the fake clock's time by duration d.

• Triggers all timers scheduled before new time
• Executes AfterFunc callbacks synchronously
• Updates all tickers
• Triggers context timeouts/deadlines
• Thread-safe

FakeClock.SetTime

func (f *FakeClock) SetTime(t time.Time)

Sets the fake clock to specific time t.

• Can only move time forward (panics if t is before current time)
• Triggers all timers and contexts with deadlines before t
• Thread-safe

FakeClock.HasWaiters

func (f *FakeClock) HasWaiters() bool

Returns true if there are active timers, tickers, or contexts.

• Useful for test assertions
• Includes: timers, tickers, AfterFunc callbacks, contexts
• Thread-safe

FakeClock.BlockUntilReady

func (f *FakeClock) BlockUntilReady()

Blocks until all pending timer operations are delivered.

• Ensures timer channel sends are processed
• Useful for test synchronization
• Thread-safe

Thread Safety

All clockz operations are thread-safe.

RealClock:

• Delegates to thread-safe time package functions
• No additional synchronization needed

FakeClock:

• Uses sync.RWMutex for time access
• Separate mutex for context operations
• Safe for concurrent timer/ticker creation
• Safe for concurrent time advancement

Performance

RealClock:

• Zero overhead: direct delegation to time package
• No allocations beyond time package needs

FakeClock:

• O(n) time advancement where n = number of waiters
• Timers sorted by target time
• Synchronous AfterFunc execution
• Minimal allocations for timer tracking