lazyref

Documentation

Index

• Constants
• type ExpirationProvider
  • func NewGraduatingExpirationProvider(initialExpiry, increments, maxExpiry time.Duration) ExpirationProvider
  • func NewSimpleExpirationProvider(expiry time.Duration) ExpirationProvider
• type ExpirationType
• type Finalizer
• type Initializer
• type Opt
  • func WithAbsoluteExpiration(expiration time.Duration) Opt
  • func WithExpirationProvider(expirationProvider ExpirationProvider, expiryType ExpirationType) Opt
  • func WithFinalizer(finalizer Finalizer) Opt
  • func WithIdleExpiration(expiration time.Duration) Opt
  • func WithRefreshInterval(initialInit, refreshPeriod time.Duration) Opt
• type Reference
  • func New(initializer Initializer, opts ...Opt) *Reference
  • func (r *Reference) Close()
  • func (r *Reference) Get() (interface{}, error)
  • func (r *Reference) MustGet() interface{}

Examples

• Reference
• Reference (Expiring)
• Reference (Refreshing)

Constants

const (
	// InitOnFirstAccess specifies that the reference should be initialized the first time it is accessed
	InitOnFirstAccess time.Duration = time.Duration(-1)

	// InitImmediately specifies that the reference should be initialized immediately after it is created
	InitImmediately time.Duration = time.Duration(0)
)

Types

type ExpirationProvider

type ExpirationProvider func() time.Duration

ExpirationProvider is a function that returns the expiration time of a reference

func NewGraduatingExpirationProvider

func NewGraduatingExpirationProvider(initialExpiry, increments, maxExpiry time.Duration) ExpirationProvider

NewGraduatingExpirationProvider returns an expiration provider that has an initial expiration and then expires in graduated increments with a maximum expiration time.

func NewSimpleExpirationProvider

func NewSimpleExpirationProvider(expiry time.Duration) ExpirationProvider

NewSimpleExpirationProvider returns an expiration provider that sets the given expiration period

type ExpirationType

type ExpirationType uint

ExpirationType indicates how to handle expiration of the reference

const (
	// LastAccessed specifies that the expiration time is calculated
	// from the last access time
	LastAccessed ExpirationType = iota

	// LastInitialized specifies that the expiration time is calculated
	// from the time the reference was initialized
	LastInitialized

	// Refreshing indicates that the reference should be periodically refreshed
	Refreshing
)

type Finalizer

type Finalizer func()

Finalizer is a function that is called when the reference is closed

type Initializer

type Initializer func() (interface{}, error)

Initializer is a function that initializes the value

type Opt

type Opt func(ref *Reference)

Opt is a reference option

func WithAbsoluteExpiration

func WithAbsoluteExpiration(expiration time.Duration) Opt

WithAbsoluteExpiration sets the expiration time for the reference. It will expire after this time period, regardless of whether or not it has been recently accessed.

func WithExpirationProvider

func WithExpirationProvider(expirationProvider ExpirationProvider, expiryType ExpirationType) Opt

WithExpirationProvider sets the expiration provider, which determines the expiration time of the reference

func WithFinalizer

func WithFinalizer(finalizer Finalizer) Opt

WithFinalizer sets a finalizer function that is called when the reference is closed or if it expires

func WithIdleExpiration

func WithIdleExpiration(expiration time.Duration) Opt

WithIdleExpiration sets the idle-time expiration for the reference. The reference is expired after not being accessed for the given duration.

func WithRefreshInterval

func WithRefreshInterval(initialInit, refreshPeriod time.Duration) Opt

WithRefreshInterval specifies that the reference should be proactively refreshed. Argument, initialInit, if greater than or equal to 0, indicates that the reference should be initialized after this duration. If less than 0, the reference will be initialized on first access. Argument, refreshPeriod, is the period at which the reference will be refreshed. Note that the Finalizer will not be invoked each time the value is refreshed.

type Reference

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

Reference holds a value that is initialized on first access using the provided Initializer function. The Reference has an optional expiring feature wherin the value is reset after the provided period of time. A subsequent call to Get or MustGet causes the Initializer function to be invoked again. The Reference also has a proactive refresh capability, in which the Initializer function is periodically called out of band (out of band means that the caller of Get or MustGet does not need to wait for the initializer function to complete: the old value will be used until the new value has finished initializing). An optional Finalizer function may be provided to be invoked whenever the Reference is closed (via a call to Close) or if it expires. (Note: The Finalizer function is not called every time the value is refreshed with the periodic refresh feature.)

Example

ref := New(func() (interface{}, error) {
	return "Value1", nil
})
fmt.Println(ref.MustGet())

Output:

Value1

Example (Expiring)

sequence := 0
ref := New(
	func() (interface{}, error) {
		sequence++
		return fmt.Sprintf("Data_%d", sequence), nil
	},
	WithIdleExpiration(2*time.Second),
)

for i := 0; i < 5; i++ {
	fmt.Println(ref.MustGet())
	time.Sleep(time.Second)
}

Example (Refreshing)

This example demonstrates a refreshing reference. The reference is initialized immediately after creation and every 2 seconds thereafter.

sequence := 0
ref := New(
	func() (interface{}, error) {
		sequence++
		return fmt.Sprintf("Data_%d", sequence), nil
	},
	WithRefreshInterval(InitImmediately, 2*time.Second),
)

for i := 0; i < 5; i++ {
	fmt.Println(ref.MustGet())
	time.Sleep(3 * time.Second)
}

func New

func New(initializer Initializer, opts ...Opt) *Reference

New creates a new reference

func (*Reference) Close

func (r *Reference) Close()

Close ensures that the finalizer (if provided) is called. Close should be called for expiring references and rerences that specify finalizers.

func (*Reference) Get

func (r *Reference) Get() (interface{}, error)

Get returns the value, or an error if the initialiser returned an error.

func (*Reference) MustGet

func (r *Reference) MustGet() interface{}

MustGet returns the value. If an error is returned during initialization of the value then this function will panic.