core

Documentation

Overview

Package cachex 提供自研高性能内存缓存库: 并发分片、精确 LRU 淘汰、独立 TTL 过期与 Singleflight 击穿防护, 与 errx / logx 生态打通,零第三方依赖。

Index

• Constants
• func GetOrSet(ctx context.Context, c *Cache, key string, ttl time.Duration, ...) (any, error)
• type Cache
  • func New(opts ...Option) (*Cache, error)
  • func (c *Cache) Cleanup()
  • func (c *Cache) Clear()
  • func (c *Cache) Close()
  • func (c *Cache) Delete(key string) bool
  • func (c *Cache) Get(key string) (any, bool)
  • func (c *Cache) Len() int
  • func (c *Cache) Set(key string, value any)
  • func (c *Cache) SetTTL(key string, value any, ttl time.Duration)
  • func (c *Cache) Stats() Stats
• type CacheEvent
• type EventHook
• type EvictReason
  • func (r EvictReason) String() string
• type Metrics
• type Option
  • func WithCapacity(n int) Option
  • func WithCleanupInterval(d time.Duration) Option
  • func WithDefaultTTL(d time.Duration) Option
  • func WithEventHook(h EventHook) Option
  • func WithLRURefresh(interval int) Option
  • func WithMetrics(m Metrics) Option
  • func WithOnEvicted(fn func(key string, value any, reason EvictReason)) Option
  • func WithShards(n int) Option
  • func WithTraceHook(h TraceHook) Option
• type Stats
• type TraceAttr
• type TraceHook

Constants

const (
	// CodeInvalidConfig 配置非法。
	CodeInvalidConfig errx.Code = "CACHEX_INVALID_CONFIG"
)

错误码定义:cachex 各失败场景的错误码。

const Version = "v1.4.1"

Version 是当前库版本，与 git tag 保持一致。

Functions

func GetOrSet

func GetOrSet(ctx context.Context, c *Cache, key string, ttl time.Duration,
	loader func(context.Context) (any, error)) (any, error)

GetOrSet 命中返回缓存值;未命中时合并并发回源,只执行一次 loader。 loader 成功按 ttl 写入缓存;失败不缓存,错误透传给全部等待者; 等待者 ctx 取消立即返回,不中断执行者。

Types

type Cache

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

Cache 是自研内存缓存入口,持有分片、统计与生命周期。 所有方法并发安全,可在多个 goroutine 间共享。

func New

func New(opts ...Option) (*Cache, error)

New 创建缓存。配置非法时返回 CACHEX_INVALID_CONFIG。

func (*Cache) Cleanup

func (c *Cache) Cleanup()

Cleanup 手动清理全部过期条目,幂等且并发安全。

func (*Cache) Clear

func (c *Cache) Clear()

Clear 清空全部条目,不触发逐出回调。

func (*Cache) Close

func (c *Cache) Close()

Close 停止后台清理任务,幂等可重复调用。 不冻结缓存:后续读写仍可用,只是不再自动清理。

func (*Cache) Delete

func (c *Cache) Delete(key string) bool

Delete 删除条目,返回是否命中。

func (*Cache) Get

func (c *Cache) Get(key string) (any, bool)

Get 读取条目:命中返回并刷新 LRU 顺序; 不存在或已过期返回 false(过期条目即时删除)。

func (*Cache) Len

func (c *Cache) Len() int

Len 返回当前条目数(全局原子计数)。

func (*Cache) Set

func (c *Cache) Set(key string, value any)

Set 写入条目,使用默认 TTL;已存在时更新值并刷新 LRU 位置。

func (*Cache) SetTTL

func (c *Cache) SetTTL(key string, value any, ttl time.Duration)

SetTTL 写入条目并指定 TTL;ttl <= 0 表示永不过期。 容量超限时按 LRU 逐出最久未用条目。

func (*Cache) Stats

func (c *Cache) Stats() Stats

Stats 返回运行统计快照。

type CacheEvent

type CacheEvent struct {
	// Action 操作类型：get_hit / get_miss / set / delete / clear / evict。
	Action string
	// Key 键名；Clear 等全局操作为空。
	Key string
	// Err 操作结果错误；nil 表示成功。
	Err error
}

CacheEvent 描述一次缓存操作事件。

type EventHook

type EventHook interface {
	// OnCacheEvent 在缓存操作结束时调用。
	OnCacheEvent(ctx context.Context, e CacheEvent)
}

EventHook 是可选事件钩子（默认 no-op），由 eventx 等外部适配器接入。

type EvictReason

type EvictReason uint8

EvictReason 是条目被移除的原因。

const (
	// EvictCapacity 容量超限,LRU 逐出。
	EvictCapacity EvictReason = iota
	// EvictExpired 条目过期被清理。
	EvictExpired
)

func (EvictReason) String

func (r EvictReason) String() string

String 返回逐出原因的稳定名称。

type Metrics

type Metrics = metricsx.Sink

Metrics 是最小指标协议（家族统一契约，定义见 metricsx.Sink）。 调用方按 Sink 签名传入标签切片；无标签时传 nil。

type Option

type Option func(*config)

Option 修改 Cache 配置,在 New 时按顺序应用。

func WithCapacity

func WithCapacity(n int) Option

WithCapacity 设置总条目上限;0 表示不限制(默认 10000)。

func WithCleanupInterval

func WithCleanupInterval(d time.Duration) Option

WithCleanupInterval 设置后台清理间隔;0 关闭后台清理(默认 1 分钟)。

func WithDefaultTTL

func WithDefaultTTL(d time.Duration) Option

WithDefaultTTL 设置默认过期时长;0 表示永不过期(默认)。 显式 SetTTL 仍可覆盖单个条目。

func WithEventHook

func WithEventHook(h EventHook) Option

WithEventHook 设置事件钩子；不设置时 no-op。

func WithLRURefresh

func WithLRURefresh(interval int) Option

WithLRURefresh 设置 LRU 刷新策略:1 表示精确 LRU (每次命中都移动链表,默认);>1 表示采样刷新 (每 interval 次命中移动一次,写锁竞争降至 1/interval)。

func WithMetrics

func WithMetrics(m Metrics) Option

WithMetrics 注入指标钩子,空表示关闭指标(默认)。

func WithOnEvicted

func WithOnEvicted(fn func(key string, value any, reason EvictReason)) Option

WithOnEvicted 设置逐出回调:容量逐出与过期清理时在锁外调用, 回调内可安全反查或写入 cache。Clear 不触发回调。

func WithShards

func WithShards(n int) Option

WithShards 设置分片数量(必须大于 0,默认 16)。

func WithTraceHook

func WithTraceHook(h TraceHook) Option

WithTraceHook 设置回源加载链路追踪钩子。

type Stats

type Stats struct {
	// Hits 命中次数。
	Hits uint64
	// Misses 未命中次数。
	Misses uint64
	// Sets 写入次数(含更新)。
	Sets uint64
	// Deletes 显式删除次数。
	Deletes uint64
	// Evictions 容量逐出次数。
	Evictions uint64
	// Expired 过期清理次数(惰性 + 后台)。
	Expired uint64
	// Len 当前条目数。
	Len int
	// Capacity 条目上限(0 表示不限)。
	Capacity int
}

Stats 是缓存运行统计快照,并发安全。

type TraceAttr

type TraceAttr = contract.TraceAttr

TraceAttr 链路追踪属性（家族统一契约，定义见 tracex/contract）。

type TraceHook

type TraceHook = contract.TraceHook

TraceHook 链路追踪钩子（家族统一契约，定义见 tracex/contract）。