1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
# Cache
An deamonless in-memory caching library with persistant snapshots.
## Features
- **In-Memory Cache**: Fast access to cached data.
- **Uses Generics with serialization**: To make it type safe and support several types via msgpack.
- **File-Backed Storage**: Persistent storage of cache data.
- **Eviction Policies**: Support for FIFO, LRU, LFU, and LTR eviction policies.
- **Concurrency**: Thread-safe operations with the use of locks(mutex). The persistant storage is locked via file locks to avoid issues
- **Periodic Tasks**: Background worker for snapshotting and cleanup of expired entries.
## Installation
To use the Cache Library in your Go project, you can install it using `go get`:
```sh
go get github.com/marcthe12/cache
```
## Usage
### Opening a Cache
To open a file-backed cache, use the `OpenFile` function:
```go
package main
import (
"github.com/marcthe12/cache"
"time"
"log"
)
func main() {
db, err := cache.OpenFile[string, string]("cache.db", cache.WithPolicy(cache.PolicyLRU))
if err != nil {
log.Fatal(err)
}
defer db.Close()
// Set a key-value pair with a TTL of 1 hour
if err := db.Set("key", "value", 1*time.Hour); err != nil {
log.Fatal(err)
}
// Get a value by key
value, ttl, err := db.GetValue("key")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Value: %s, TTL: %v\n", value, ttl)
}
```
To open an in-memory cache, use the `OpenMem` function:
```go
package main
import (
"github.com/marcthe12/cache"
"time"
"log"
)
func main() {
db, err := cache.OpenMem[string, string](cache.WithPolicy(cache.PolicyLRU))
if err != nil {
log.Fatal(err)
}
defer db.Close()
// Set a key-value pair with a TTL of 1 hour
if err := db.Set("key", "value", 1*time.Hour); err != nil {
log.Fatal(err)
}
// Get a value by key
value, ttl, err := db.GetValue("key")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Value: %s, TTL: %v\n", value, ttl)
// Get a value with a pointer by key(Useful if the value type is an interface).
var value string
value, ttl, err := db.GetValue(&value)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Value: %s, TTL: %v\n", value, ttl)
}
```
More Examples in the ```/examples``` directory
### Eviction Policies
The Cache Library supports the following eviction policies:
- **None**: Does not do any evictions.
- **FIFO (First In, First Out)**: Evicts the oldest entries first.
- **LRU (Least Recently Used)**: Evicts the least recently used entries first.
- **LFU (Least Frequently Used)**: Evicts the least frequently used entries first.
- **LTR (Least Remaining Time)**: Evicts entries with the least remaining time to live first.
You can set the eviction policy when opening the cache using the `WithPolicy` option.
### Configuration Options
The Cache Library supports the following configuration options:
- `WithPolicy`: Sets the eviction policy.
- `WithMaxCost`: Sets the maximum cost for the cache. The Cost is the size of the binary encoded KV pair.
- `SetSnapshotTime`: Sets the interval for taking snapshots of the cache.
- `SetCleanupTime`: Sets the interval for cleaning up expired entries.
### Additional Methods
- `Get`: Retrieves a value from the cache by key and returns its TTL. It take an out pointer.
- `GetValue`: Retrieves a value from the cache by key and returns the value and its TTL.
- `Set`: Adds a key-value pair to the cache with a specified TTL.
- `Delete`: Removes a key-value pair from the cache.
- `UpdateInPlace`: Retrieves a value from the cache, processes it using the provided function, and then sets the result back into the cache with the same key.
- `Memorize`: Attempts to retrieve a value from the cache. If the retrieval fails, it sets the result of the factory function into the cache and returns that result. Note this locks the db duing the factory function which prevent concurent acces to the db during the operation.
## Documentation
For detailed documentation on the public API, you can use `godoc`:
```sh
godoc -http=:6060
```
Then open your browser and navigate to `http://localhost:6060/pkg/github.com/marcthe12/cache`.
|
