README
¶
go-structr
A library with a series of performant data types with automated struct value indexing. Indexing is supported via arbitrary combinations of fields, and in the case of the cache type, negative results (errors!) are also supported.
Under the hood, go-structr maintains a hashmap per index, where each hashmap is a hashmap keyed by serialized input key type. This is handled by the incredibly performant serialization library go-mangler, which at this point in time supports most arbitrary types (other than maps, channels, functions), so feel free to index by by almost anything!
See the docs for more API information.
Notes
This is a core underpinning of GoToSocial's performance.
Documentation
¶
Index ¶
- Constants
- func DefaultIgnoreErr(err error) bool
- type Cache
- func (c *Cache[T]) Cap() int
- func (c *Cache[T]) Clear()
- func (c *Cache[T]) Debug() map[string]any
- func (c *Cache[T]) Get(index *Index, keys ...Key) []T
- func (c *Cache[T]) GetOne(index *Index, key Key) (T, bool)
- func (c *Cache[T]) Index(name string) *Index
- func (c *Cache[T]) Init(config CacheConfig[T])
- func (c *Cache[T]) Invalidate(index *Index, keys ...Key)
- func (c *Cache[T]) Len() int
- func (c *Cache[T]) Load(index *Index, keys []Key, load func([]Key) ([]T, error)) ([]T, error)
- func (c *Cache[T]) LoadOne(index *Index, key Key, load func() (T, error)) (T, error)
- func (c *Cache[T]) Put(values ...T)
- func (c *Cache[T]) Store(value T, store func() error) error
- func (c *Cache[T]) Trim(perc float64)
- type CacheConfig
- type Direction
- type Index
- type IndexConfig
- type Key
- type Queue
- func (q *Queue[T]) Debug() map[string]any
- func (q *Queue[T]) Index(name string) *Index
- func (q *Queue[T]) Init(config QueueConfig[T])
- func (q *Queue[T]) Len() int
- func (q *Queue[T]) MoveBack(index *Index, keys ...Key)
- func (q *Queue[T]) MoveFront(index *Index, keys ...Key)
- func (q *Queue[T]) Pop(index *Index, keys ...Key) []T
- func (q *Queue[T]) PopBack() (T, bool)
- func (q *Queue[T]) PopBackN(n int) []T
- func (q *Queue[T]) PopFront() (T, bool)
- func (q *Queue[T]) PopFrontN(n int) []T
- func (q *Queue[T]) PushBack(values ...T)
- func (q *Queue[T]) PushFront(values ...T)
- type QueueConfig
- type QueueCtx
- func (q *QueueCtx[T]) Debug() map[string]any
- func (q *QueueCtx[T]) PopBack(ctx context.Context) (T, bool)
- func (q *QueueCtx[T]) PopFront(ctx context.Context) (T, bool)
- func (q *QueueCtx[T]) PushBack(values ...T)
- func (q *QueueCtx[T]) PushFront(values ...T)
- func (q *QueueCtx[T]) Wait() <-chan struct{}
- type Timeline
- func (t *Timeline[T, PK]) Clear()
- func (t *Timeline[T, PK]) Debug() map[string]any
- func (t *Timeline[T, PK]) Index(name string) *Index
- func (t *Timeline[T, PK]) Init(config TimelineConfig[T, PK])
- func (t *Timeline[T, PK]) Insert(values ...T)
- func (t *Timeline[T, PK]) Invalidate(index *Index, keys ...Key)
- func (t *Timeline[T, PK]) Len() int
- func (t *Timeline[T, PK]) Range(dir Direction) func(yield func(T) bool)
- func (t *Timeline[T, PK]) RangeKeys(index *Index, keys ...Key) func(yield func(T) bool)
- func (t *Timeline[T, PK]) Select(min, max *PK, length *int, dir Direction) (values []T)
- func (t *Timeline[T, PK]) Trim(max int, dir Direction)
- type TimelineConfig
Constants ¶
const ( // Asc = ascending, i.e. bottom-up. Asc = Direction(true) // Desc = descending, i.e. top-down. Desc = Direction(false) )
Variables ¶
This section is empty.
Functions ¶
func DefaultIgnoreErr ¶
DefaultIgnoreErr is the default function used to ignore (i.e. not cache) incoming error results during Load() calls. By default ignores context pkg errors.
Types ¶
type Cache ¶
type Cache[StructType any] struct { // contains filtered or unexported fields }
Cache provides a structure cache with automated indexing and lookups by any initialization-defined combination of fields. This also supports caching of negative results (errors!) returned by LoadOne().
func (*Cache[T]) Get ¶
Get fetches values from the cache stored under index, using precalculated index keys.
func (*Cache[T]) GetOne ¶
GetOne fetches value from cache stored under index, using precalculated index key.
func (*Cache[T]) Init ¶
func (c *Cache[T]) Init(config CacheConfig[T])
Init initializes the cache with given configuration including struct fields to index, and necessary fns.
func (*Cache[T]) Invalidate ¶
Invalidate invalidates all results stored under index keys. Note that if set, this will call the invalidate hook on each.
func (*Cache[T]) Load ¶
Load fetches values from the cache stored under index, using precalculated index keys. The cache will attempt to results with values stored under keys, passing keys with uncached results to the provider load callback to further hydrate the cache with missing results. Cached error results not included or returned by this function.
func (*Cache[T]) LoadOne ¶
LoadOneBy fetches one result from the cache stored under index, using precalculated index key. In the case that no result is found, provided load callback will be used to hydrate the cache.
func (*Cache[T]) Put ¶
func (c *Cache[T]) Put(values ...T)
Put will insert the given values into cache, calling any invalidate hook on each value.
type CacheConfig ¶ added in v0.6.0
type CacheConfig[StructType any] struct { // IgnoreErr defines which errors to // ignore (i.e. not cache) returned // from load function callback calls. // This may be left as nil, on which // DefaultIgnoreErr will be used. IgnoreErr func(error) bool // Copy provides a means of copying // cached values, to ensure returned values // do not share memory with those in cache. Copy func(StructType) StructType // Invalidate is called when cache values // (NOT errors) are invalidated, either // as the values passed to Put() / Store(), // or by the keys by calls to Invalidate(). Invalidate func(StructType) // Indices defines indices to create // in the Cache for the receiving // generic struct type parameter. Indices []IndexConfig // MaxSize defines the maximum number // of items allowed in the Cache at // one time, before old items start // getting evicted. MaxSize int }
CacheConfig defines config vars for initializing a Cache{} type.
type Direction ¶ added in v0.9.0
type Direction bool
Direction defines a direction to iterate entries in a Timeline.
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index is an exposed Cache internal model, used to extract struct keys, generate hash checksums for them and store struct results by the init defined config. This model is exposed to provide faster lookups in the case that you would like to manually provide the used index via the Cache.___By() series of functions, or access the underlying index key generator.
func (*Index) Key ¶ added in v0.3.0
Key generates Key{} from given parts for the type of lookup this Index uses in cache. NOTE: panics on incorrect no. parts / types given.
type IndexConfig ¶
type IndexConfig struct {
// Fields should contain a comma-separated
// list of struct fields used when generating
// keys for this index. Nested fields should
// be specified using periods. An example:
// "Username,Favorites.Color"
//
// Note that nested fields where the nested
// struct field is a ptr are supported, but
// nil ptr values in nesting will result in
// that particular value NOT being indexed.
// e.g. with "Favorites.Color" if *Favorites
// is nil then it will not be indexed.
//
// Field types supported include any of those
// supported by the `go-mangler` library.
Fields string
// Multiple indicates whether to accept multiple
// possible values for any single index key. The
// default behaviour is to only accept one value
// and overwrite existing on any write operation.
Multiple bool
// AllowZero indicates whether to accept zero
// value fields in index keys. i.e. whether to
// index structs for this set of field values
// IF any one of those field values is the zero
// value for that type. The default behaviour
// is to skip indexing structs for this lookup
// when any of the indexing fields are zero.
AllowZero bool
}
IndexConfig defines config variables for initializing a struct index.
type Key ¶ added in v0.5.0
type Key struct {
// contains filtered or unexported fields
}
Key represents one key to lookup (potentially) stored entries in an Index.
func (Key) Key ¶ added in v0.6.0
Key returns the underlying cache key string. NOTE: this will not be log output friendly.
type Queue ¶ added in v0.6.0
type Queue[StructType any] struct { // contains filtered or unexported fields }
Queue provides a structure model queue with automated indexing and popping by any init defined lookups of field combinations.
func (*Queue[T]) Index ¶ added in v0.6.0
Index selects index with given name from queue, else panics.
func (*Queue[T]) Init ¶ added in v0.6.0
func (q *Queue[T]) Init(config QueueConfig[T])
Init initializes the queue with given configuration including struct fields to index, and necessary fns.
func (*Queue[T]) MoveBack ¶ added in v0.6.0
MoveBack attempts to move values indexed under any of keys to the back of the queue.
func (*Queue[T]) MoveFront ¶ added in v0.6.0
MoveFront attempts to move values indexed under any of keys to the front of the queue.
func (*Queue[T]) Pop ¶ added in v0.6.0
Pop attempts to pop values from queue indexed under any of keys.
func (*Queue[T]) PopBackN ¶ added in v0.6.0
PopBackN attempts to pop n values from back of the queue.
func (*Queue[T]) PopFrontN ¶ added in v0.6.0
PopFrontN attempts to pop n values from front of the queue.
type QueueConfig ¶ added in v0.6.0
type QueueConfig[StructType any] struct { // Pop is called when queue values // are popped, during calls to any // of the Pop___() series of fns. Pop func(StructType) // Indices defines indices to create // in the Queue for the receiving // generic struct parameter type. Indices []IndexConfig }
QueueConfig defines config vars for initializing a struct queue.
type QueueCtx ¶ added in v0.7.0
type QueueCtx[StructType any] struct { Queue[StructType] // contains filtered or unexported fields }
QueueCtx is a context-aware form of Queue{}.
func (*QueueCtx[T]) PopBack ¶ added in v0.7.0
PopBack pops the current value at back of the queue, else blocking on ctx.
func (*QueueCtx[T]) PopFront ¶ added in v0.7.0
PopFront pops the current value at front of the queue, else blocking on ctx.
func (*QueueCtx[T]) PushBack ¶ added in v0.7.0
func (q *QueueCtx[T]) PushBack(values ...T)
PushBack pushes values to back of queue.
type Timeline ¶ added in v0.9.0
Timeline provides an ordered-list like cache of structures, with automated indexing and invalidation by any initialization defined combination of fields. The list order is maintained according to the configured struct primary key.
func (*Timeline[T, PK]) Clear ¶ added in v0.9.0
func (t *Timeline[T, PK]) Clear()
Clear empties the timeline by calling .TrimBottom(0, Down).
func (*Timeline[T, PK]) Index ¶ added in v0.9.0
Index selects index with given name from timeline, else panics.
func (*Timeline[T, PK]) Init ¶ added in v0.9.0
func (t *Timeline[T, PK]) Init(config TimelineConfig[T, PK])
Init initializes the timeline with given configuration including struct fields to index, and necessary fns.
func (*Timeline[T, PK]) Insert ¶ added in v0.9.0
func (t *Timeline[T, PK]) Insert(values ...T)
Insert will insert the given values into the timeline, calling any set invalidate hook on each inserted value.
func (*Timeline[T, PK]) Invalidate ¶ added in v0.9.0
Invalidate invalidates all entries stored in index under given keys. Note that if set, this will call the invalidate hook on each value.
func (*Timeline[T, PK]) Range ¶ added in v0.9.0
Range will range over all values in the timeline in given direction. dir = Asc : ranges from the bottom-up. dir = Desc : ranges from the top-down.
Please note that the entire Timeline{} will be locked for the duration of the range operation, i.e. from the beginning of the first yield call until the end of the last.
func (*Timeline[T, PK]) RangeKeys ¶ added in v0.9.0
RangeKeys will iterate over all values for given keys in the given index.
Please note that the entire Timeline{} will be locked for the duration of the range operation, i.e. from the beginning of the first yield call until the end of the last.
func (*Timeline[T, PK]) Select ¶ added in v0.9.0
Select allows you to retrieve a slice of values, in order, from the timeline. This slice is defined by the minimum and maximum primary key parameters, up to a given length in size. The direction in which you select will determine which of the min / max primary key values is used as the *cursor* to begin the start of the selection, and which is used as the *boundary* to mark the end, if set. In either case, the length parameter is always optional.
dir = Asc : cursors up from 'max' (required), with boundary 'min' (optional). dir = Desc : cursors down from 'min' (required), with boundary 'max' (optional).
type TimelineConfig ¶ added in v0.9.0
type TimelineConfig[StructType any, PK cmp.Ordered] struct { // Copy provides a means of copying // timelined values, to ensure returned values // do not share memory with those in timeline. Copy func(StructType) StructType // Invalidate is called when timelined // values are invalidated, either as passed // to Insert(), or by calls to Invalidate(). Invalidate func(StructType) // PKey defines the generic parameter StructType's // field to use as the primary key for this cache. // It must be ordered so that the timeline can // maintain correct sorting of inserted values. // // Field selection logic follows the same path as // with IndexConfig{}.Fields. Noting that in this // case only a single field is permitted, though // it may be nested, and as described above the // type must conform to cmp.Ordered. PKey string // Indices defines indices to create // in the Timeline for the receiving // generic struct type parameter. Indices []IndexConfig }
TimelineConfig defines config vars for initializing a Timeline{}.
Source Files