1VMEMCACHE(3) PMDK Programmer's Manual VMEMCACHE(3)
2
6 vmemcache - buffer-based LRU cache
7
9 #include <libvmemcache.h>
10 VMEMcache *vmemcache_new();
12 void vmemcache_delete(VMEMcache *cache);
13 int vmemcache_set_eviction_policy(VMEMcache *cache,
14 enum vmemcache_repl_p repl_p);
15 int vmemcache_set_size(VMEMcache *cache, size_t size);
16 int vmemcache_set_extent_size(VMEMcache *cache, size_t extent_size);
17 int vmemcache_add(VMEMcache *cache, const char *path);
18 void vmemcache_callback_on_evict(VMEMcache *cache,
20 vmemcache_on_evict *evict, void *arg);
21 void vmemcache_callback_on_miss(VMEMcache *cache,
22 vmemcache_on_miss *miss, void *arg);
23 ssize_t vmemcache_get(VMEMcache *cache,
25 const void *key, size_t key_size,
26 void *vbuf, size_t vbufsize, size_t offset, size_t *vsize);
27 int vmemcache_put(VMEMcache *cache,
29 const void *key, size_t key_size,
30 const void *value, size_t value_size);
31 int vmemcache_exists(VMEMcache *cache,
33 const void *key, size_t key_size);
34 int vmemcache_evict(VMEMcache *cache, const void *key, size_t ksize);
36 int vmemcache_get_stat(VMEMcache *cache,
38 enum vmemcache_statistic stat,
39 void *value, size_t value_size);
40 const char *vmemcache_errormsg(void);
42
44 libvmemcache is a volatile key-value store optimized for operating on
45 NVDIMM based space, although it can work with any filesystem, stored in
46 memory (tmpfs) or, less performant, on some kind of a disk.
47 Creation
49 VMEMcache *vmemcache_new();
50 Creates an empty unconfigured vmemcache instance.
51 int vmemcache_set_size(VMEMcache *cache, size_t size);
53 Sets the size of the cache; it will be rounded up towards a
54 whole page size alignment (4KB on x86).
55 int vmemcache_set_extent_size(VMEMcache *cache, size_t extent_size);
57 Sets block size of the cache – 256 bytes minimum, strongly rec‐
58 ommended to be a multiple of 64 bytes. If the cache is backed
59 by a non byte-addressable medium, the extent size should be 4096
60 (or a multiple) or performance will greatly suffer.
61 int vmemcache_set_eviction_policy(VMEMcache *cache, enum vmemcache_re‐
63 pl_p repl_p);
64 Sets what should happen on a put into a full cache.
65 • VMEMCACHE_REPLACEMENT_NONE: manual eviction only - puts into a
67 full cache will fail
68 • VMEMCACHE_REPLACEMENT_LRU: least recently accessed entry will
70 be evicted to make space when needed
71 int vmemcache_add(VMEMcache *cache, const char *path);
73 Associate the cache with a backing medium in the given path,
74 which may be:
75 • a /dev/dax device
77 • a directory on a regular filesystem (which may or may not be
79 mounted with -o dax, either on persistent memory or any other
80 backing storage)
81 void vmemcache_delete(VMEMcache *cache);
83 Frees any structures associated with the cache.
84 Use
86 ssize_t vmemcache_get(VMEMcache *cache, const void *key, size_t
87 key_size, void *vbuf, size_t vbufsize, size_t offset, size_t *vsize);
88 Searches for an entry with the given key; it doesn’t have to be
89 zero-terminated or be text - any sequence of bytes of length
90 key_size is okay. If found, the entry’s value is copied to vbuf
91 that has space for vbufsize bytes, optionally skipping offset
92 bytes at the start. No matter if the copy was truncated or not,
93 its true size is stored into vsize; vsize remains unmodified if
94 the key was not found.
95 Return value is number of bytes successfully copied, or -1 on
97 error. In particular, if there’s no entry for the given key in
98 the cache, the errno will be ENOENT.
99 int vmemcache_put(VMEMcache *cache, const void *key, size_t key_size,
101 const void *value, size_t value_size);
102 Inserts the given key:value pair into the cache. Returns 0 on
103 success, -1 on error. Inserting a key that already exists will
104 fail with EEXIST.
105 int vmemcache_exists(VMEMcache *cache, const void *key, size_t
107 key_size, size_t *vsize);
108 Searches for an entry with the given key, and returns 1 if
109 found, 0 if not found, and -1 if search couldn’t be performed.
110 The size of the found entry is stored into vsize; vsize remains
111 unmodified if the key was not found. This function does not im‐
112 pact the replacement policy or statistics.
113 int vmemcache_evict(VMEMcache *cache, const void *key, size_t ksize);
115 Removes the given key from the cache. If key is null and there
116 is a replacement policy set, the oldest entry will be removed.
117 Returns 0 if an entry has been evicted, -1 otherwise.
118 Callbacks
120 You can register a hook to be called during eviction or after a cache
121 miss, using vmemcache_callback_on_evict() or vmemcache_call‐
122 back_on_miss(), respectively:
123 void vmemcache_callback_on_evict(VMEMcache *cache, vmemcache_on_evict
125 *evict, void *arg);
126 void vmemcache_callback_on_miss(VMEMcache *cache, vmemcache_on_miss
128 *miss, void *arg);
129 The extra arg will be passed to your function.
131 A hook to be called during eviction has to have the following signa‐
133 ture:
134 void vmemcache_on_evict(VMEMcache *cache, const void *key, size_t
136 key_size, void *arg);
137 Called when an entry is being removed from the cache. The evic‐
138 tion can’t be prevented, but until the callback returns, the en‐
139 try remains available for queries. The thread that triggered
140 the eviction is blocked in the meantime.
141 A hook to be called after a cache miss has to have the following signa‐
143 ture:
144 void vmemcache_on_miss(VMEMcache *cache, const void *key, size_t
146 key_size, void *arg);
147 Called when a get query fails, to provide an opportunity to in‐
148 sert the missing key. If the callback calls put for that spe‐
149 cific key, the get will return its value, even if it did not fit
150 into the cache.
151 Misc
153 int vmemcache_get_stat(VMEMcache *cache, enum vmemcache_statistic stat,
154 void *value, size_t value_size);
155 Obtains a piece of statistics about the cache. The stat may be:
156 • VMEMCACHE_STAT_PUT – count of puts
158 • VMEMCACHE_STAT_GET – count of gets
160 • VMEMCACHE_STAT_HIT – count of gets that were served from the
162 cache
163 • VMEMCACHE_STAT_MISS – count of gets that were not present in
165 the cache
166 • VMEMCACHE_STAT_EVICT – count of evictions
168 • VMEMCACHE_STAT_ENTRIES – current number of cache entries
170 (key:value pairs)
171 • VMEMCACHE_STAT_DRAM_SIZE_USED – current amount of DRAM used
173 • VMEMCACHE_STAT_POOL_SIZE_USED – current usage of data pool
175 • VMEMCACHE_STAT_HEAP_ENTRIES – current number of discontiguous
177 unused regions (ie, free space fragmentation)
178 Statistics are enabled by default. They can be disabled at the compile
180 time of the vmemcache library if the STATS_ENABLED CMake option is set
181 to OFF.
182 const char *vmemcache_errormsg(void);
184 Retrieves a human-friendly description of the last error.
185 Errors
187 On an error, a machine-usable description is passed in errno. It may
188 be:
189 • EINVAL – nonsensical/invalid parameter
191 • ENOMEM – out of DRAM
193 • EEXIST – (put) entry for that key already exists
195 • ENOENT – (evict, get) no entry for that key
197 • ESRCH – (evict) could not find an evictable entry
199 • EAGAIN – (evict) an entry was used and could not be evicted, please
201 try again
202 • ENOSPC – (create, put) not enough space in the memory pool
204PMDK - 2022-01-22 VMEMCACHE(3)