Documentation
¶
Index ¶
- Constants
- Variables
- type Options
- type Store
- func (s *Store) Append(key string, appends map[string]string) error
- func (s *Store) Close()
- func (s *Store) Decrement(key string, offsets map[string]int64) error
- func (s *Store) Delete(key string) (bool, error)
- func (s *Store) Exists(key string) (bool, error)
- func (s *Store) Get(key string) (any, error)
- func (s *Store) GetTTL(key string) (int64, error)
- func (s *Store) Increment(key string, offsets map[string]int64) error
- func (s *Store) MultiDelete(keys []string) (map[string]bool, error)
- func (s *Store) MultiGet(keys []string) (map[string]any, error)
- func (s *Store) MultiSet(items map[string]map[string]any, ttl time.Duration) (map[string]bool, error)
- func (s *Store) Set(key string, value map[string]any, ttl time.Duration) (bool, error)
- func (s *Store) SetTTL(key string, ttl time.Duration) error
Constants ¶
const (
ShardCount uint8 = 128 // default number of shards
)
Variables ¶
var ( ErrNotFound = errors.New("flashdb: key not found") // not in cache ErrBadType = errors.New("flashdb: value type mismatch") // type assertion failed ErrIllegalField = errors.New("flashdb: illegal or missing field") // e.g. empty key ErrInvalidKey = errors.New("flashdb: invalid/empty key") // e.g. malformed key )
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
Shards uint8 // default 64
MaxStorageSize uint64 // REQUIRED: per-store budget in bytes (split evenly per shard)
DefaultTTL time.Duration // default TTL
JanitorEvery time.Duration // default 1m (0 disables)
LFUDepth int // default 4
LFUWidth uint64 // default 1<<16
LFUAgingEvery uint64 // default 200_000
}
Options for FlashDB. These options control the behavior and limits of the in-memory store.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store satisfies caching.Cache (see compile-time check below).
We shard the map; each shard maintains its own LRU and cost accounting. TinyLFU is shared to keep a global popularity signal (simple and effective).
func (*Store) Append ¶
Append appends strings to existing string fields in the record. Returns ErrNotFound if key missing/expired, ErrIllegalField if field absent, ErrBadType if value is not a string.
func (*Store) Decrement ¶
Decrement decreases numeric fields in the record by given offsets. Internally calls Increment with negative values.
func (*Store) Delete ¶
Delete removes a key if it exists. Returns true if the key existed and was removed. Returns false if the key was missing or invalid. Does not error if the key is missing.
func (*Store) Exists ¶
Exists checks if a key exists and is not expired. Does not update recency or frequency. Returns false for missing, expired, or invalid keys.
func (*Store) Get ¶
Get fetches a value by its (already-composed) key. Lazy-expires, bumps LRU recency, and records TinyLFU access. Returns ErrNotFound for missing or expired keys.
func (*Store) GetTTL ¶
GetTTL returns the remaining TTL (in seconds) for key. Returns -1 if the record has no TTL, and ErrNotFound if the key is missing or expired.
func (*Store) Increment ¶
Increment increases numeric fields in the record by given offsets. Supported types: int, int32, int64, float64. Returns ErrNotFound if key missing/expired, ErrIllegalField if field absent, ErrBadType if value type is not numeric.
func (*Store) MultiDelete ¶
MultiDelete deletes all provided keys. Returns per-key deletion success. A key is true if it existed and was removed; false if it was missing or invalid.
func (*Store) MultiGet ¶
MultiGet returns a map of key -> value for all found (and not-expired) keys. Missing or expired keys are silently omitted.
func (*Store) MultiSet ¶
func (s *Store) MultiSet(items map[string]map[string]any, ttl time.Duration) (map[string]bool, error)
MultiSet sets many keys with the same TTL. Returns per-key success. A key is true if it was stored (admitted and within budget); false if rejected (e.g., TinyLFU admission fail) or the key was invalid.
func (*Store) Set ¶
Set stores/updates a value under key with an optional TTL. Returns true if stored, false if rejected by TinyLFU admission. Enforces per-shard byte budget using key+record size.
Notes:
- ttl==0 uses s.opts.DefaultTTL (if > 0). Adjust unit mapping as per your option.
- Uses your deep-size estimator; we add a small record overhead to approximate metadata.
- All mutations happen under the shard write lock.
Source Files