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, const void *key, size_t
84 key_size, void *vbuf, size_t vbufsize, size_t offset, size_t *vsize);
85 Searches for an entry with the given key; it doesn’t have to be
86 zero-terminated or be text - any sequence of bytes of length
87 key_size is okay. If found, the entry’s value is copied to vbuf
88 that has space for vbufsize bytes, optionally skipping offset
89 bytes at the start. No matter if the copy was truncated or not,
90 its true size is stored into vsize; vsize remains unmodified if
91 the key was not found.
92 Return value is number of bytes successfully copied, or -1 on
94 error. In particular, if there’s no entry for the given key in
95 the cache, the errno will be ENOENT.
96 int vmemcache_put(VMEMcache *cache, const void *key, size_t key_size,
98 const void *value, size_t value_size);
99 Inserts the given key:value pair into the cache. Returns 0 on
100 success, -1 on error. Inserting a key that already exists will
101 fail with EEXIST.
102 int vmemcache_evict(VMEMcache *cache, const void *key, size_t ksize);
104 Removes the given key from the cache. If key is null and there
105 is a replacement policy set, the oldest entry will be removed.
106 Returns 0 if an entry has been evicted, -1 otherwise.
107 Callbacks
109 You can register a hook to be called during eviction or after a cache
110 miss, using vmemcache_callback_on_evict() or vmemcache_call‐
111 back_on_miss(), respectively. The extra arg will be passed to your
112 function.
113 void vmemcache_on_evict(VMEMcache *cache, const void *key, size_t
115 key_size, void *arg);
116 Called when an entry is being removed from the cache. The evic‐
117 tion can’t be prevented, but until the callback returns, the en‐
118 try remains available for queries. The thread that triggered
119 the eviction is blocked in the meantime.
120 void vmemcache_on_miss(VMEMcache *cache, const void *key, size_t
122 key_size, void *arg);
123 Called when a get query fails, to provide an opportunity to in‐
124 sert the missing key. If the callback calls put for that spe‐
125 cific key, the get will return its value, even if it did not fit
126 into the cache.
127 Misc
129 int vmemcache_get_stat(VMEMcache *cache, enum vmemcache_statistic stat,
130 void *value, size_t value_size);
131 Obtains a piece of statistics about the cache. The stat may be:
132 · VMEMCACHE_STAT_PUT – count of puts
134 · VMEMCACHE_STAT_GET – count of gets
136 · VMEMCACHE_STAT_HIT – count of gets that were served from the
138 cache
139 · VMEMCACHE_STAT_MISS – count of gets that were not present in
141 the cache
142 · VMEMCACHE_STAT_EVICT – count of evictions
144 · VMEMCACHE_STAT_ENTRIES – current number of cache entries
146 · VMEMCACHE_STAT_DRAM_SIZE_USED – current amount of DRAM used
148 for keys CLARIFY/RENAME: doesn’t include index, repl nor allo‐
149 cator
150 · VMEMCACHE_STAT_POOL_SIZE_USED – current usage of data pool
152 · VMEMCACHE_STAT_HEAP_ENTRIES – current number of heap entries
154 Statistics are enabled by default. They can be disabled at the compile
156 time of the libvmemcache library if the STATS_ENABLED CMake option is
157 set to OFF.
158 const char *vmemcache_errormsg(void);
160 Retrieves a human-friendly description of the last error.
161 Errors
163 On an error, a machine-usable description is passed in errno. It may
164 be:
165 · EINVAL – nonsensical/invalid parameter
167 · ENOMEM – out of DRAM
169 · EEXIST – (put) entry for that key already exists
171 · ENOENT – (evict, get) no entry for that key
173 · ESRCH – (evict) could not find an evictable entry
175 · EAGAIN – (evict) an entry was used and could not be evicted, please
177 try again
178 · ENOSPC – (create, put) not enough space in the memory pool
180PMDK - 2020-01-31 VMEMCACHE(3)