go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/common/clock/clock.go (about)

     1  // Copyright 2014 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package clock is an interface to system time and timers which is easy to
    16  // test.
    17  package clock
    18  
    19  import (
    20  	"context"
    21  	"time"
    22  )
    23  
    24  // Clock is an interface to system time.
    25  //
    26  // The standard clock is SystemClock, which falls through to the system time
    27  // library. Another clock, FakeClock, is available to simulate time facilities
    28  // for testing.
    29  type Clock interface {
    30  	// Returns the current time (see time.Now).
    31  	Now() time.Time
    32  
    33  	// Sleeps the current goroutine (see time.Sleep).
    34  	//
    35  	// Sleep will return a TimerResult containing the time when it was awakened
    36  	// and detailing its execution. If the sleep terminated prematurely from
    37  	// cancellation, the TimerResult's Incomplete() method will return true.
    38  	Sleep(context.Context, time.Duration) TimerResult
    39  
    40  	// Creates a new Timer instance, bound to this Clock.
    41  	//
    42  	// If the supplied Context is canceled, the timer will expire immediately.
    43  	NewTimer(ctx context.Context) Timer
    44  }