bucket

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 21, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BucketedResourceApplicator 

type BucketedResourceApplicator[BucketedResource any] func(context.Context, BucketedResource) error

BucketedResourceApplicator is an applicator to apply changes to a bucketed value.

type Buckets 

type Buckets[BucketKey any, BucketedResource any] interface {
	// Add adds a bucket for the given key and resource ID.
	// If a resource already exists for the given resource ID, it will be overwritten.
	Add(ctx context.Context, bucketKey BucketKey, resource BucketedResource) error

	// AddIfNotExists adds the result of the given creator at the given bucket key
	// if it does not already exist. It returns either the pre-existing resource or the created resource.
	AddIfNotExists(ctx context.Context, bucketKey BucketKey, creator func(context.Context, BucketKey) (BucketedResource, error)) (BucketedResource, error)

	// Apply applies a change to bucketed resource.
	// It returns false if the bucket value doesn't exist and, thus, the applicator could not be executed against the resource.
	Apply(ctx context.Context, bucketKey BucketKey, applicator BucketedResourceApplicator[BucketedResource]) (bool, error)

	// EvictOlderThan evicts all buckets in this collection that were added prior to the given time.
	// It returns any resources that were evicted.
	EvictOlderThan(ctx context.Context, evictionTime time.Time) ([]BucketedResource, error)

	// Pop gets the desired bucket, if it exists. It will be removed from the internal storage of this buckets item.
	Pop(ctx context.Context, bucketKey BucketKey) (BucketedResource, bool, error)
}

Buckets describes a collection of buckets.

type BucketsList 

type BucketsList[BucketKey ListKey[ResourceID], ResourceID comparable, BucketedResource any] struct {
	// contains filtered or unexported fields
}

BucketsList is a list of buckets implementing the Buckets interface.

func NewBucketsList 

func NewBucketsList[BucketKey ListKey[ResourceID], ResourceID comparable, BucketedResource any](bucketCount uint16) (*BucketsList[BucketKey, ResourceID, BucketedResource], error)

NewBucketsList creates a new instance of [List] with a number of buckets equal to the given count. The given function is used to create new, empty instances of buckets.

func (*BucketsList[BucketKey, ResourceID, BucketedResource]) Add 

func (l *BucketsList[BucketKey, ResourceID, BucketedResource]) Add(ctx context.Context, bucketKey BucketKey, resource BucketedResource) error

func (*BucketsList[BucketKey, ResourceID, BucketedResource]) AddIfNotExists 

func (l *BucketsList[BucketKey, ResourceID, BucketedResource]) AddIfNotExists(ctx context.Context, bucketKey BucketKey, creator func(context.Context, BucketKey) (BucketedResource, error)) (BucketedResource, error)

func (*BucketsList[BucketKey, ResourceID, BucketedResource]) Apply 

func (l *BucketsList[BucketKey, ResourceID, BucketedResource]) Apply(ctx context.Context, bucketKey BucketKey, applicator BucketedResourceApplicator[BucketedResource]) (bool, error)

func (*BucketsList[BucketKey, ResourceID, BucketedResource]) EvictOlderThan 

func (l *BucketsList[BucketKey, ResourceID, BucketedResource]) EvictOlderThan(_ context.Context, evictionTime time.Time) ([]BucketedResource, error)

func (*BucketsList[BucketKey, ResourceID, BucketedResource]) Pop 

func (l *BucketsList[BucketKey, ResourceID, BucketedResource]) Pop(ctx context.Context, bucketKey BucketKey) (BucketedResource, bool, error)

type ListKey 

type ListKey[ResourceID comparable] interface {
	// BucketIndex fetches the bucket index in which a particular entry belongs.
	// This index is expected to be consistent with the maximum number of buckets specified
	// in the container. This index is 0-based - so, if the number of buckets is 64,
	// this value must return an integer value in the range of [0, 64).
	BucketIndex() int

	// ResourceID returns the ID of the resource being bucketed.
	ResourceID() ResourceID
}

ListKey is a bucket key oriented toward bucket identification with a [List] instance.

type MultiValueBucketResource 

type MultiValueBucketResource[ValueID any, Value any] interface {
	// Add adds the given value to this bucket. If a value for the given ID
	// is already present in this bucket, then it is replaced with the given value.
	Add(ctx context.Context, id ValueID, value Value) error

	// EvictValuesOlderThan evicts any values that were added to the bucket
	// prior to the given time.
	// This returns all the values that were evicted.
	EvictValuesOlderThan(ctx context.Context, evictionTime time.Time) ([]Value, error)

	// IsEmpty determines if this resource has no values associated with it.
	IsEmpty() bool

	// PopValues pops values contained within this bucket for the given IDs.
	PopValues(ctx context.Context, ids []ValueID) ([]Value, error)

	// Size returns the number of values stored within this bucket.
	Size() int
}

MultiValueBucketResource describes a bucket that contains multiple values and defines means to access those values.

type MultiValueBuckets 

type MultiValueBuckets[BucketKey any, BucketedResource MultiValueBucketResource[MultiValueID, MultiValue], MultiValueID any, MultiValue any] interface {
	Buckets[BucketKey, BucketedResource]

	// EvictValuesOlderThan evicts any values that were added
	// prior to the given time. This executes across all buckets.
	// This returns all of the resources that were evicted.
	EvictValuesOlderThan(ctx context.Context, evictionTime time.Time) ([]MultiValue, error)

	// PopValues pops values out of the given identified bucket. This will not pop the bucket itself -
	// merely values contained within the bucket itself. If there is no bucket for the given key,
	// the returned list of values will be empty and there will be no error.
	PopValues(ctx context.Context, bucketKey BucketKey, ids []MultiValueID) ([]MultiValue, error)
}

MultiValueBuckets is a Buckets extension that supports MultiValueBucketResource.

type MultiValueBucketsList 

type MultiValueBucketsList[BucketKey ListKey[ResourceID], ResourceID comparable, BucketedResource MultiValueBucketResource[MultiValueID, MultiValue], MultiValueID comparable, MultiValue any] struct {
	*BucketsList[BucketKey, ResourceID, BucketedResource]
}

MultiValueBucketsList is a BucketsList extension that supports multi-value buckets.

func NewMultiValueBucketsList 

func NewMultiValueBucketsList[BucketKey ListKey[ResourceID], ResourceID comparable, BucketedResource MultiValueBucketResource[MultiValueID, MultiValue], MultiValueID comparable, MultiValue any](bucketCount uint16) (*MultiValueBucketsList[BucketKey, ResourceID, BucketedResource, MultiValueID, MultiValue], error)

NewMultiValueBucketsList creates a new instance of MultiValueBucketsList.

func (*MultiValueBucketsList[BucketKey, ResourceID, BucketedResource, MultiValueID, MultiValue]) EvictValuesOlderThan 

func (l *MultiValueBucketsList[BucketKey, ResourceID, BucketedResource, MultiValueID, MultiValue]) EvictValuesOlderThan(ctx context.Context, evictionTime time.Time) ([]MultiValue, error)

func (*MultiValueBucketsList[BucketKey, ResourceID, BucketedResource, MultiValueID, MultiValue]) PopValues 

func (l *MultiValueBucketsList[BucketKey, ResourceID, BucketedResource, MultiValueID, MultiValue]) PopValues(ctx context.Context, bucketKey BucketKey, ids []MultiValueID) ([]MultiValue, error)

type MultiValueResource 

type MultiValueResource[MultiValueID comparable, MultiValue any] struct {
	// contains filtered or unexported fields
}

MultiValueResource is an OrderedMultiValueBucketResource implementation.

func NewMultiValueResource 

func NewMultiValueResource[MultiValueID comparable, MultiValue any]() *MultiValueResource[MultiValueID, MultiValue]

NewMultiValueResource creates a new instance of MultiValueResource.

func (*MultiValueResource[MultiValueID, MultiValue]) Add 

func (v *MultiValueResource[MultiValueID, MultiValue]) Add(_ context.Context, id MultiValueID, value MultiValue) error

func (*MultiValueResource[MultiValueID, MultiValue]) EvictValuesOlderThan 

func (v *MultiValueResource[MultiValueID, MultiValue]) EvictValuesOlderThan(_ context.Context, evictionTime time.Time) ([]MultiValue, error)

func (*MultiValueResource[ValueID, Value]) IsEmpty 

func (v *MultiValueResource[ValueID, Value]) IsEmpty() bool

func (*MultiValueResource[MultiValueID, MultiValue]) PopFirst 

func (v *MultiValueResource[MultiValueID, MultiValue]) PopFirst(_ context.Context, n int) ([]MultiValue, error)

func (*MultiValueResource[MultiValueID, MultiValue]) PopValues 

func (v *MultiValueResource[MultiValueID, MultiValue]) PopValues(_ context.Context, ids []MultiValueID) ([]MultiValue, error)

func (*MultiValueResource[MultiValueID, MultiValue]) RetainLast 

func (v *MultiValueResource[MultiValueID, MultiValue]) RetainLast(_ context.Context, n int) ([]MultiValue, error)

func (*MultiValueResource[MultiValueID, MultiValue]) Size 

func (v *MultiValueResource[MultiValueID, MultiValue]) Size() int

type OrderedMultiValueBucketResource 

type OrderedMultiValueBucketResource[ValueID any, Value any] interface {
	MultiValueBucketResource[ValueID, Value]

	// PopFirst pops the first N resources within this bucket.
	// If N is greater than the count of items in this bucket,
	// it will merely pop all values in the bucket (and not error).
	PopFirst(ctx context.Context, n int) ([]Value, error)

	// RetainLast will pop all but the N most-recent values within this bucket.
	// It returns all the values that were evicted from the bucket.
	RetainLast(ctx context.Context, n int) ([]Value, error)
}

OrderedMultiValueBucketResource is an extension of MultiValueBucketResource that provides guarantees of tracking values' order.

type StringListKey 

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

StringListKey is an implementation of ListKey using a string value.

func NewStringListKey 

func NewStringListKey(resourceID string, bucketCount uint16) (*StringListKey, error)

NewStringListKey builds a new instance of a StringListKey.

func (*StringListKey) BucketIndex 

func (k *StringListKey) BucketIndex() int

func (*StringListKey) ResourceID 

func (k *StringListKey) ResourceID() string

func (*StringListKey) String 

func (k *StringListKey) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.