1VMEMCACHE(3)               PMDK Programmer's Manual               VMEMCACHE(3)
2
3
4

NAME

6       vmemcache - buffer-based LRU cache
7

SYNOPSIS

9              #include <libvmemcache.h>
10
11              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
19              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
24              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
28              int vmemcache_put(VMEMcache *cache,
29                  const void *key, size_t key_size,
30                  const void *value, size_t value_size);
31
32              int vmemcache_exists(VMEMcache *cache,
33                  const void *key, size_t key_size);
34
35              int vmemcache_evict(VMEMcache *cache, const void *key, size_t ksize);
36
37              int vmemcache_get_stat(VMEMcache *cache,
38                  enum vmemcache_statistic stat,
39                  void *value, size_t value_size);
40
41              const char *vmemcache_errormsg(void);
42

DESCRIPTION

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
48   Creation
49       VMEMcache *vmemcache_new();
50              Creates an empty unconfigured vmemcache instance.
51
52       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
56       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
62       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
66VMEMCACHE_REPLACEMENT_NONE: manual eviction only - puts into a
67                full cache will fail
68
69VMEMCACHE_REPLACEMENT_LRU:  least recently accessed entry will
70                be evicted to make space when needed
71
72       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
76              • a /dev/dax device
77
78              • 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
82       void vmemcache_delete(VMEMcache *cache);
83              Frees any structures associated with the cache.
84
85   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
96              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
100       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
106       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
114       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
119   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
124       void vmemcache_callback_on_evict(VMEMcache  *cache,  vmemcache_on_evict
125       *evict, void *arg);
126
127       void   vmemcache_callback_on_miss(VMEMcache  *cache,  vmemcache_on_miss
128       *miss, void *arg);
129
130       The extra arg will be passed to your function.
131
132       A hook to be called during eviction has to have  the  following  signa‐
133       ture:
134
135       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
142       A hook to be called after a cache miss has to have the following signa‐
143       ture:
144
145       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
152   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
157VMEMCACHE_STAT_PUT – count of puts
158
159VMEMCACHE_STAT_GET – count of gets
160
161VMEMCACHE_STAT_HIT  –  count of gets that were served from the
162                cache
163
164VMEMCACHE_STAT_MISS – count of gets that were not  present  in
165                the cache
166
167VMEMCACHE_STAT_EVICT – count of evictions
168
169VMEMCACHE_STAT_ENTRIES  current  number  of  cache  entries
170                (key:value pairs)
171
172VMEMCACHE_STAT_DRAM_SIZE_USED – current amount of DRAM used
173
174VMEMCACHE_STAT_POOL_SIZE_USED – current usage of data pool
175
176VMEMCACHE_STAT_HEAP_ENTRIES – current number of  discontiguous
177                unused regions (ie, free space fragmentation)
178
179       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
183       const char *vmemcache_errormsg(void);
184              Retrieves a human-friendly description of the last error.
185
186   Errors
187       On  an  error, a machine-usable description is passed in errno.  It may
188       be:
189
190EINVAL – nonsensical/invalid parameter
191
192ENOMEM – out of DRAM
193
194EEXIST – (put) entry for that key already exists
195
196ENOENT – (evict, get) no entry for that key
197
198ESRCH – (evict) could not find an evictable entry
199
200EAGAIN – (evict) an entry was used and could not be  evicted,  please
201         try again
202
203ENOSPC – (create, put) not enough space in the memory pool
204
205
206
207PMDK -                            2021-07-23                      VMEMCACHE(3)
Impressum