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_evict(VMEMcache *cache, const void *key, size_t ksize);
33 int vmemcache_get_stat(VMEMcache *cache,
35 enum vmemcache_statistic stat,
36 void *value, size_t value_size);
37 const char *vmemcache_errormsg(void);
39
41 libvmemcache is a volatile key-value store optimized for operating on
42 NVDIMM based space, although it can work with any filesystem, be it
43 stored in memory (tmpfs) or, less performant, on some kind of a disk.
44 Creation
46 VMEMcache *vmemcache_new();
47 Creates an empty unconfigured vmemcache instance.
48 int vmemcache_set_size(VMEMcache *cache, size_t size);
50 Sets the size of the cache; it will be rounded up towards a
51 whole page size alignment (4KB on x86).
52 int vmemcache_set_extent_size(VMEMcache *cache, size_t extent_size);
54 Sets block size of the cache – 256 bytes minimum, strongly rec‐
55 ommended to be a multiple of 64 bytes. If the cache is backed
56 by a non byte-addressable medium, the extent size should be 4096
57 (or a multiple) or performance will greatly suffer.
58 int vmemcache_set_eviction_policy(VMEMcache *cache, enum vmemcache_re‐
60 pl_p repl_p);
61 Sets what should happen on a put into a full cache.
62 · VMEMCACHE_REPLACEMENT_NONE: manual eviction only - puts into a
64 full cache will fail
65 · VMEMCACHE_REPLACEMENT_LRU: least recently accessed entry will
67 be evicted to make space when needed
68 int vmemcache_add(VMEMcache *cache, const char *path);
70 Associate the cache with a backing medium in the given path,
71 which may be:
72 · a /dev/dax device
74 · a directory on a regular filesystem (which may or may not be
76 mounted with -o dax, either on persistent memory or any other
77 backing)
78 void vmemcache_delete(VMEMcache *cache);
80 Frees any structures associated with the cache.
81 Use
83 ssize_t vmemcache_get(VMEMcache *cache, con‐
84 st void *key, size_t key_size, void *vbuf, size_t vbufsize, size_t off‐
85 set, size_t *vsize);
86 Searches for an entry with the given key; it doesn't have to be
87 zero-terminated or be text - any sequence of bytes of length
88 key_size is okay. If found, the entry's value is copied to vbuf
89 that has space for vbufsize bytes, optionally skipping offset
90 bytes at the start. No matter if the copy was truncated or not,
91 its true size is stored into vsize; vsize remains unmodified if
92 the key was not found.
93 Return value is number of bytes successfully copied, or -1 on
95 error. In particular, if there's no entry for the given key in
96 the cache, the errno will be ENOENT.
97 int vmemcache_put(VMEMcache *cache, con‐
99 st void *key, size_t key_size, const void *value, size_t value_size);
100 Inserts the given key:value pair into the cache. Returns 0 on
101 success, -1 on error. Inserting a key that already exists will
102 fail with EEXIST.
103 int vmemcache_evict(VMEMcache *cache, const void *key, size_t ksize);
105 Removes the given key from the cache. If key is null and there
106 is a replacement policy set, the oldest entry will be removed.
107 Returns 0 if an entry has been evicted, -1 otherwise.
108 Callbacks
110 You can register a hook to be called during eviction or after a cache
111 miss, using vmemcache_callback_on_evict() or vmemcache_call‐
112 back_on_miss(), respectively. The extra arg will be passed to your
113 function.
114 void vmemcache_on_evict(VMEMcache *cache, con‐
116 st void *key, size_t key_size, void *arg);
117 Called when an entry is being removed from the cache. The evic‐
118 tion can't be prevented, but until the callback returns, the en‐
119 try remains available for queries. The thread that triggered
120 the eviction is blocked in the meantime.
121 void vmemcache_on_miss(VMEMcache *cache, con‐
123 st void *key, size_t key_size, void *arg);
124 Called when a get query fails, to provide an opportunity to in‐
125 sert the missing key. If the callback calls put for that spe‐
126 cific key, the get will return its value, even if it did not fit
127 into the cache.
128 Misc
130 int vmemcache_get_stat(VMEMcache *cache, enum vmemcache_statis‐
131 tic stat, void *value, size_t value_size);
132 Obtains a piece of statistics about the cache. The stat may be:
133 · VMEMCACHE_STAT_PUT – count of puts
135 · VMEMCACHE_STAT_GET – count of gets
137 · VMEMCACHE_STAT_HIT – count of gets that were served from the
139 cache
140 · VMEMCACHE_STAT_MISS – count of gets that were not present in
142 the cache
143 · VMEMCACHE_STAT_EVICT – count of evictions
145 · VMEMCACHE_STAT_ENTRIES – current number of cache entries
147 · VMEMCACHE_STAT_DRAM_SIZE_USED – current amount of DRAM used
149 for keys CLARIFY/RENAME: doesn't include index, repl nor allo‐
150 cator
151 · VMEMCACHE_STAT_POOL_SIZE_USED – current usage of data pool
153 · VMEMCACHE_STAT_HEAP_ENTRIES – current number of heap entries
155 Statistics are enabled by default. They can be disabled at the compile
157 time of the libvmemcache library if the STATS_ENABLED CMake option is
158 set to OFF.
159 const char *vmemcache_errormsg(void);
161 Retrieves a human-friendly description of the last error.
162 Errors
164 On an error, a machine-usable description is passed in errno. It may
165 be:
166 · EINVAL – nonsensical/invalid parameter
168 · ENOMEM – out of DRAM
170 · EEXIST – (put) entry for that key already exists
172 · ENOENT – (evict, get) no entry for that key
174 · ESRCH – (evict) could not find an evictable entry
176 · EAGAIN – (evict) an entry was used and could not be evicted, please
178 try again
179 · ENOSPC – (create, put) not enough space in the memory pool
181PMDK - 2019-07-27 VMEMCACHE(3)