lazy

Documentation

Overview

Package lazy provides types for lazily initialized values.

Index

• func GFunc[T any](fill func() T) func() T
• func GFuncErr[T any](fill func() (T, error)) func() (T, error)
• func SyncFunc[T any](fill func() T) func() T
• func SyncFuncErr[T any](fill func() (T, error)) func() (T, error)
• type DeferredFuncs
  • func (d *DeferredFuncs) Defer(f func() error) bool
  • func (d *DeferredFuncs) MustDefer(f func() error)
• type DeferredInit
  • func (d *DeferredInit) Do() error
  • func (d *DeferredInit) Funcs() *DeferredFuncs
• type GValue
  • func (z *GValue[T]) Get(fill func() T) T
  • func (z *GValue[T]) GetErr(fill func() (T, error)) (T, error)
  • func (z *GValue[T]) MustSet(val T)
  • func (z *GValue[T]) Set(v T) bool
• type SyncValue
  • func (z *SyncValue[T]) Get(fill func() T) T
  • func (z *SyncValue[T]) GetErr(fill func() (T, error)) (T, error)
  • func (z *SyncValue[T]) MustSet(val T)
  • func (z *SyncValue[T]) Peek() (v T, ok bool)
  • func (z *SyncValue[T]) PeekErr() (v T, err error, ok bool)
  • func (z *SyncValue[T]) Set(val T) bool
  • func (z *SyncValue[T]) SetForTest(tb TB, val T, err error)
• type TB

Functions

func GFunc

func GFunc[T any](fill func() T) func() T

GFunc wraps a function to make it lazy.

The returned function calls fill the first time it's called, and returns fill's result on every subsequent call.

The returned function is not safe for concurrent use.

func GFuncErr

func GFuncErr[T any](fill func() (T, error)) func() (T, error)

SyncFuncErr wraps a function to make it lazy.

The returned function calls fill the first time it's called, and returns fill's results on every subsequent call.

The returned function is not safe for concurrent use.

func SyncFunc

func SyncFunc[T any](fill func() T) func() T

SyncFunc wraps a function to make it lazy.

The returned function calls fill the first time it's called, and returns fill's result on every subsequent call.

The returned function is safe for concurrent use.

func SyncFuncErr

func SyncFuncErr[T any](fill func() (T, error)) func() (T, error)

SyncFuncErr wraps a function to make it lazy.

The returned function calls fill the first time it's called, and returns fill's results on every subsequent call.

The returned function is safe for concurrent use.

Types

type DeferredFuncs

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

DeferredFuncs allows one or more funcs to be deferred until the owner's DeferredInit.Do method is called for the first time.

DeferredFuncs is safe for concurrent use.

func (*DeferredFuncs) Defer

func (d *DeferredFuncs) Defer(f func() error) bool

Defer adds a function to be called when DeferredInit.Do is called for the first time. It returns true on success, or false if DeferredInit.Do has already been called.

func (*DeferredFuncs) MustDefer

func (d *DeferredFuncs) MustDefer(f func() error)

MustDefer is like DeferredFuncs.Defer, but panics if DeferredInit.Do has already been called.

type DeferredInit

type DeferredInit struct {
	DeferredFuncs
}

DeferredInit allows one or more funcs to be deferred until DeferredInit.Do is called for the first time.

DeferredInit is safe for concurrent use.

func (*DeferredInit) Do

func (d *DeferredInit) Do() error

Do calls previously deferred init functions if it is being called for the first time on this instance of DeferredInit. It stops and returns an error if any init function returns an error.

It is safe for concurrent use, and the deferred init is guaranteed to have been completed, either successfully or with an error, when Do() returns.

func (*DeferredInit) Funcs

func (d *DeferredInit) Funcs() *DeferredFuncs

Funcs is a shorthand for &d.DeferredFuncs. The returned value can safely be passed to external code, allowing to defer init funcs without also exposing DeferredInit.Do.

type GValue

type GValue[T any] struct {
	V T
	// contains filtered or unexported fields
}

GValue is a lazily computed value.

Use either Get or GetErr, depending on whether your fill function returns an error.

Recursive use of a GValue from its own fill function will panic.

GValue is not safe for concurrent use. (Mnemonic: G is for one Goroutine, which isn't strictly true if you provide your own synchronization between goroutines, but in practice most of our callers have been using it within a single goroutine.)

func (*GValue[T]) Get

func (z *GValue[T]) Get(fill func() T) T

Get returns z's value, calling fill to compute it if necessary. f is called at most once.

func (*GValue[T]) GetErr

func (z *GValue[T]) GetErr(fill func() (T, error)) (T, error)

GetErr returns z's value, calling fill to compute it if necessary. f is called at most once, and z remembers both of fill's outputs.

func (*GValue[T]) MustSet

func (z *GValue[T]) MustSet(val T)

MustSet sets z's value to val, or panics if z already has a value.

func (*GValue[T]) Set

func (z *GValue[T]) Set(v T) bool

Set attempts to set z's value to val, and reports whether it succeeded. Set only succeeds if none of Get/GetErr/Set have been called before.

type SyncValue

type SyncValue[T any] struct {
	// contains filtered or unexported fields
}

SyncValue is a lazily computed value.

Use either Get or GetErr, depending on whether your fill function returns an error.

Recursive use of a SyncValue from its own fill function will deadlock.

SyncValue is safe for concurrent use.

func (*SyncValue[T]) Get

func (z *SyncValue[T]) Get(fill func() T) T

Get returns z's value, calling fill to compute it if necessary. f is called at most once.

func (*SyncValue[T]) GetErr

func (z *SyncValue[T]) GetErr(fill func() (T, error)) (T, error)

GetErr returns z's value, calling fill to compute it if necessary. f is called at most once, and z remembers both of fill's outputs.

func (*SyncValue[T]) MustSet

func (z *SyncValue[T]) MustSet(val T)

MustSet sets z's value to val, or panics if z already has a value.

func (*SyncValue[T]) Peek

func (z *SyncValue[T]) Peek() (v T, ok bool)

Peek returns z's value and a boolean indicating whether the value has been set successfully. If a value has not been set, the zero value of T is returned.

This function is safe to call concurrently with Get/GetErr/Set, but it's undefined whether a value set by a concurrent call will be visible to Peek.

To get any error that's been set, use PeekErr.

If GetErr's fill function returned a valid T and an non-nil error, Peek discards that valid T value. PeekErr returns both.

func (*SyncValue[T]) PeekErr

func (z *SyncValue[T]) PeekErr() (v T, err error, ok bool)

PeekErr returns z's value and error and a boolean indicating whether the value or error has been set. If ok is false, T and err are the zero value.

This function is safe to call concurrently with Get/GetErr/Set, but it's undefined whether a value set by a concurrent call will be visible to Peek.

Unlike Peek, PeekErr reports ok if either v or err has been set, not just v, and returns both the T and err returned by GetErr's fill function.

func (*SyncValue[T]) Set

func (z *SyncValue[T]) Set(val T) bool

Set attempts to set z's value to val, and reports whether it succeeded. Set only succeeds if none of Get/GetErr/Set have been called before.

func (*SyncValue[T]) SetForTest

func (z *SyncValue[T]) SetForTest(tb TB, val T, err error)

SetForTest sets z's value and error. It's used in tests only and reverts z's state back when tb and all its subtests complete. It is not safe for concurrent use and must not be called concurrently with any SyncValue methods, including another call to itself.

type TB

type TB interface {
	Helper()
	Cleanup(func())
}

TB is a subset of testing.TB that we use to set up test helpers. It's defined here to avoid pulling in the testing package.