README
¶
cache
This go module provides a very simple in-memory key/value cache. It uses no mutex locks; utilizing only 1 go routine, 2 channels, and 1 or 2 tickers depending on if you enable the pruner. The module also exports git/miss statistics that you can plug into expvar, or other metrics modules.
This module has a concept of pruning. Items can be marked prunable,
or not prunable. Those marked prunable are deleted after they have not
had a get requst within a specified duration. Those marked not-prunable
have a different configurable maximum unused age.
I wrote this to cache data from mysql queries for an nginx auth proxy. See a simple example in cache_test.go.
Documentation
¶
Index ¶
- type Cache
- func (c *Cache) Delete(requestKey string) bool
- func (c *Cache) ExpStats() any
- func (c *Cache) Get(requestKey string) *Item
- func (c *Cache) List() map[string]*Item
- func (c *Cache) Save(requestKey string, data any, opts Options) bool
- func (c *Cache) Start(clean bool)
- func (c *Cache) Stats() *Stats
- func (c *Cache) Stop(clean bool)
- type Config
- type Duration
- type Item
- type Options
- type Stats
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache provides methods to get a user and delete a user from cache. If the user is not in cache it is fetched using the userinfo module.
func New ¶
New starts the cache routine and returns a struct to get data from the cache. You do not need to call Start() after calling New(); it's already started.
Example ¶
package main
import (
"fmt"
"golift.io/cache"
)
func main() {
users := cache.New(cache.Config{})
defer users.Stop(true) // stop the processor go routine.
// This example just saves a string.
// The input is an interface{} so you can save more than strings.
users.Save("admin", "Super Dooper", cache.Options{})
users.Save("luser", "Under Dawggy", cache.Options{})
user := users.Get("luser")
fmt.Println("User Name:", user.Data)
users.Delete("luser")
stats := users.Stats()
fmt.Println("Gets:", stats.Gets)
fmt.Println("Hits:", stats.Hits)
fmt.Println("Miss:", stats.Misses)
fmt.Println("Save:", stats.Saves)
fmt.Println("Del:", stats.Deletes)
fmt.Println("Size:", stats.Size)
}
Output: User Name: Under Dawggy Gets: 1 Hits: 1 Miss: 0 Save: 2 Del: 1 Size: 1
func (*Cache) ExpStats ¶
ExpStats returns the stats inside of an interface{} so expvar can consume it. Use it in your app like this:
myCache := cache.New(cache.Config{})
expvar.Publish("Cache", expvar.Func(myCache.ExpStats))
/* or put it inside your own expvar map. */
myMap := expvar.NewMap("myMap")
myMap.Set("Cache", expvar.Func(myCache.ExpStats))
This will never be nil, and concurrent access is OK.
func (*Cache) Get ¶
Get returns a pointer to a copy of an item, or nil if it doesn't exist. Because it's a copy, concurrent access is OK.
func (*Cache) List ¶
List returns a copy of the in-memory cache. This will never be nil, and concurrent access is OK. The map Items will also never be nil, and because they are copies, concurrent access to Items is also OK. This method will double the memory footprint until release, and garbage collection runs. If the data stored in cache is large and not pointers, then you may not want to call this method much, or at all.
func (*Cache) Start ¶
Starts sets up the cache and starts the go routine. Call this only if you already called Stop() and wish to turn it back on. Setting clean will clear the existing cache before restarting.
type Config ¶
type Config struct {
// Prune enables the pruner routine.
// This must be enabled to use Expire time on Items.
// If you don't want other prunes to happen,
// set really long durations for PruneAfter and MaxUnused.
// @ recommend 3 minutes - 5 minutes
PruneInterval time.Duration
// PruneAfter causes the pruner routine to prune keys marked prunable
// after they have not been used for this duration.
// @default 18 minutes
PruneAfter time.Duration
// Keys not marked prunable are pruned by the pruner routine
// after they have not been used for this duration.
// @default 25 hours
MaxUnused time.Duration
// RequestAccuracy can be set between 100 milliseconds and 1 minute.
// This sets the ticker interval that updates our time.Now() variable.
// Generally, the default of 1 second should be fine for most apps.
// If accuracy about when an item was saved isn't important, you can raise
// this to a few seconds quite safely and the cache will use fewer cpu cycles.
RequestAccuracy time.Duration
}
Config provides the input options for a new cache. All the fields are optional.
type Duration ¶
Duration is used to format time duration(s) in stats output.
func (*Duration) MarshalJSON ¶
MarshalJSON turns a Duration into a string for json or expvar.
type Item ¶
type Item struct {
Data any `json:"data"`
Time time.Time `json:"created"`
Last time.Time `json:"lastAccess"`
Hits int64 `json:"hits"`
// contains filtered or unexported fields
}
Item is what's returned from a cache Get.
- Data is the input data. Type-check it back to what it should be.
- Time is when the item was saved (or updated) in cache.
- Last is the time when the last cache get for this item occurred.
- Hits is the number of cache gets for this key.
type Options ¶
type Options struct {
// Setting Prune true will allow the pruning routine to prune this item.
// Items are pruned when they have not been retreived in the PruneAfter duration.
Prune bool
// You may set a specific eviction time for an item. This only works if the
// pruner is running. The item will be removed from cache after this date/time.
// This works independently from setting Prune to true, and follows different logic.
// Not setting this, or setting it to zero time will never expire the item.
Expire time.Time
}
Options are optional, and may be provided when saving a cached item.
type Stats ¶
type Stats struct {
Size int64 // derived. Count of items in cache.
Gets int64 // derived. Cache gets issued.
Hits int64 // Gets for cached keys.
Misses int64 // Gets for missing keys.
Saves int64 // Saves for a new key.
Updates int64 // Saves that caused an update.
Deletes int64 // Delete hits.
DelMiss int64 // Delete misses.
Pruned int64 // Total items pruned.
Prunes int64 // Number of times pruner has run.
Pruning Duration // How much time has been spent pruning.
}
Stats contains the exported cache statistics.
Source Files