1PMEMKV(3) PMEMKV Programmer's Manual PMEMKV(3)
2
6 pmemkv - Key/Value Datastore for Persistent Memory
7
9 #include <libpmemkv.h>
10 typedef int pmemkv_get_kv_callback(const char *key, size_t keybytes, const char *value,
12 size_t valuebytes, void *arg);
13 typedef void pmemkv_get_v_callback(const char *value, size_t valuebytes, void *arg);
14 int pmemkv_open(const char *engine, pmemkv_config *config, pmemkv_db **db);
16 void pmemkv_close(pmemkv_db *kv);
17 int pmemkv_count_all(pmemkv_db *db, size_t *cnt);
19 int pmemkv_count_above(pmemkv_db *db, const char *k, size_t kb, size_t *cnt);
20 int pmemkv_count_below(pmemkv_db *db, const char *k, size_t kb, size_t *cnt);
21 int pmemkv_count_between(pmemkv_db *db, const char *k1, size_t kb1, const char *k2,
22 size_t kb2, size_t *cnt);
23 int pmemkv_get_all(pmemkv_db *db, pmemkv_get_kv_callback *c, void *arg);
25 int pmemkv_get_above(pmemkv_db *db, const char *k, size_t kb, pmemkv_get_kv_callback *c,
26 void *arg);
27 int pmemkv_get_below(pmemkv_db *db, const char *k, size_t kb, pmemkv_get_kv_callback *c,
28 void *arg);
29 int pmemkv_get_between(pmemkv_db *db, const char *k1, size_t kb1, const char *k2,
30 size_t kb2, pmemkv_get_kv_callback *c, void *arg);
31 int pmemkv_exists(pmemkv_db *db, const char *k, size_t kb);
33 int pmemkv_get(pmemkv_db *db, const char *k, size_t kb, pmemkv_get_v_callback *c,
35 void *arg);
36 int pmemkv_get_copy(pmemkv_db *db, const char *k, size_t kb, char *buffer,
37 size_t buffer_size, size_t *value_size);
38 int pmemkv_put(pmemkv_db *db, const char *k, size_t kb, const char *v, size_t vb);
39 int pmemkv_remove(pmemkv_db *db, const char *k, size_t kb);
41 int pmemkv_defrag(pmemkv_db *db, double start_percent, double amount_percent);
43 const char *pmemkv_errormsg(void);
45 For pmemkv configuration API description see libpmemkv_config(3). For
47 general pmemkv information, engine descriptions and bindings details
48 see libpmemkv(7).
49
51 Keys and values stored in a pmemkv database can be arbitrary binary da‐
52 ta and can contain multiple null characters. Every function which ac‐
53 cepts key expects const char *k pointer to data and its size as size_t.
54 Some of the functions (mainly range-query API) are not guaranteed to be
56 implemented by all engines. If an engine does not support a certain
57 function, it will return PMEMKV_STATUS_NOT_SUPPORTED.
58 int pmemkv_open(const char *engine, pmemkv_config *config, pmemkv_db
60 **db);
61 Opens the pmemkv database and stores a pointer to a pmemkv_db
62 instance in *db. The engine parameter specifies the engine name
63 (see libpmemkv(7) for the list of available engines). The con‐
64 fig parameter specifies configuration (see libpmemkv_config(3)
65 for details). Pmemkv takes ownership of the config parameter -
66 this means that pmemkv_config_delete() must NOT be called after
67 successful open.
68 void pmemkv_close(pmemkv_db *kv);
70 Closes pmemkv database.
71 int pmemkv_count_all(pmemkv_db *db, size_t *cnt);
73 Stores in *cnt the number of records in db.
74 int pmemkv_count_above(pmemkv_db *db, const char *k, size_t kb, size_t
76 *cnt);
77 Stores in *cnt the number of records in db whose keys are
78 greater than the key k of length kb.
79 int pmemkv_count_below(pmemkv_db *db, const char *k, size_t kb, size_t
81 *cnt);
82 Stores in *cnt the number of records in db whose keys are less
83 than the key k of length kb.
84 int pmemkv_count_between(pmemkv_db *db, const char *k1, size_t kb1,
86 const char *k2, size_t kb2, size_t *cnt);
87 Stores in *cnt the number of records in db whose keys are
88 greater than key k1 (of length kb1) and less than key k2 (of
89 length kb2).
90 int pmemkv_get_all(pmemkv_db *db, pmemkv_get_kv_callback *c, void
92 *arg);
93 Executes function c for every record stored in db. Arguments
94 passed to the function are: pointer to a key, size of the key,
95 pointer to a value, size of the value and arg specified by the
96 user. Function c can stop iteration by returning non-zero val‐
97 ue. In that case pmemkv_get_all() returns PMEMKV_STA‐
98 TUS_STOPPED_BY_CB. Returning 0 continues iteration.
99 int pmemkv_get_above(pmemkv_db *db, const char *k, size_t kb,
101 pmemkv_get_kv_callback *c, void *arg);
102 Executes function c for every record stored in db whose keys are
103 greater than key k (of length kb). Arguments passed to c are:
104 pointer to a key, size of the key, pointer to a value, size of
105 the value and arg specified by the user. Function c can stop
106 iteration by returning non-zero value. In that case
107 pmemkv_get_above() returns PMEMKV_STATUS_STOPPED_BY_CB. Return‐
108 ing 0 continues iteration.
109 int pmemkv_get_below(pmemkv_db *db, const char *k, size_t kb,
111 pmemkv_get_kv_callback *c, oid *arg);
112 Executes function c for every record stored in db whose keys are
113 less than key k (of length kb). Arguments passed to c are:
114 pointer to a key, size of the key, pointer to a value, size of
115 the value and arg specified by the user. Function c can stop
116 iteration by returning non-zero value. In that case
117 pmemkv_get_below() returns PMEMKV_STATUS_STOPPED_BY_CB. Return‐
118 ing 0 continues iteration.
119 int pmemkv_get_between(pmemkv_db *db, const char *k1, size_t kb1, const
121 char *k2, size_t kb2, pmemkv_get_kv_callback *c, void *arg);
122 Executes function c for every record stored in db whose keys are
123 greater than key k1 (of length kb1) and less than key k2 (of
124 length kb2). Arguments passed to c are: pointer to a key, size
125 of the key, pointer to a value, size of the value and arg speci‐
126 fied by the user. Function c can stop iteration by returning
127 non-zero value. In that case pmemkv_get_between() returns
128 PMEMKV_STATUS_STOPPED_BY_CB. Returning 0 continues iteration.
129 int pmemkv_exists(pmemkv_db *db, const char *k, size_t kb);
131 Checks existence of record with key k of length kb. If record
132 is present PMEMKV_STATUS_OK is returned, otherwise PMEMKV_STA‐
133 TUS_NOT_FOUND is returned. Other possible return values are de‐
134 scribed in the ERRORS section.
135 int pmemkv_get(pmemkv_db *db, const char *k, size_t kb,
137 pmemkv_get_v_callback *c, void *arg);
138 Executes function c on record with key k (of length kb). If
139 record is present and no error occurred the function returns
140 PMEMKV_STATUS_OK. If record does not exist PMEMKV_STA‐
141 TUS_NOT_FOUND is returned. Other possible return values are de‐
142 scribed in the ERRORS section. Function c is called with the
143 following parameters: pointer to a value, size of the value and
144 arg specified by the user. Value points to the location where
145 data is actually stored (no copy occurs). This function is
146 guaranteed to be implemented by all engines.
147 int pmemkv_get_copy(pmemkv_db *db, const char *k, size_t kb, char *buf‐
149 fer, size_t buffer_size, size_t *value_size);
150 Copies value of record with key k of length kb to user provided
151 buffer. buffer points to the value buffer, buffer_size speci‐
152 fies its size and *value_size is filled in by this function. If
153 the value doesn’t fit in the provided buffer then this function
154 returns PMEMKV_STATUS_UNKNOWN_ERROR. Otherwise, in absence of
155 any errors, PMEMKV_STATUS_OK is returned. Other possible return
156 values are described in the ERRORS section. This function is
157 guaranteed to be implemented by all engines.
158 int pmemkv_put(pmemkv_db *db, const char *k, size_t kb, const char *v,
160 size_t vb);
161 Inserts a key-value pair into pmemkv database. kb is the length
162 of key k and vb is the length of value v. When this function
163 returns, caller is free to reuse both buffers. This function is
164 guaranteed to be implemented by all engines.
165 int pmemkv_remove(pmemkv_db *db, const char *k, size_t kb);
167 Removes record with key k of length kb. This function is guar‐
168 anteed to be implemented by all engines.
169 int pmemkv_defrag(pmemkv_db *db, double start_percent, double
171 amount_percent);
172 Defragments approximately `amount_percent' percent of elements
173 in the database starting from `start_percent' percent of ele‐
174 ments.
175 const char *pmemkv_errormsg(void);
177 Returns a human readable string describing the last error.
178 ERRORS
180 Each function, except for pmemkv_close() and pmemkv_errormsg(), returns
181 one of the following status codes:
182 · PMEMKV_STATUS_OK – no error
184 · PMEMKV_STATUS_UNKNOWN_ERROR – unknown error
186 · PMEMKV_STATUS_NOT_FOUND – record not found
188 · PMEMKV_STATUS_NOT_SUPPORTED – function is not implemented by current
190 engine
191 · PMEMKV_STATUS_INVALID_ARGUMENT – argument to function has wrong value
193 · PMEMKV_STATUS_CONFIG_PARSING_ERROR – parsing data to config failed
195 · PMEMKV_STATUS_CONFIG_TYPE_ERROR – config item has different type than
197 expected
198 · PMEMKV_STATUS_STOPPED_BY_CB – iteration was stopped by user’s call‐
200 back
201 · PMEMKV_STATUS_OUT_OF_MEMORY – operation failed because there is not
203 enough memory (or space on the device)
204 · PMEMKV_STATUS_WRONG_ENGINE_NAME – engine name does not match any
206 available engine
207 · PMEMKV_STATUS_TRANSACTION_SCOPE_ERROR – an error with the scope of
209 the libpmemobj transaction
210 · PMEMKV_STATUS_DEFRAG_ERROR – the defragmentation process failed (pos‐
212 sibly in the middle of a run)
213 Status returned from a function can change in a future version of a li‐
215 brary to a more specific one. For example, if a function returns
216 PMEMKV_STATUS_UNKNOWN_ERROR, it is possible that in future versions it
217 will return PMEMKV_STATUS_INVALID_ARGUMENT. Recommended way to check
218 for an error is to compare status with PMEMKV_STATUS_OK.
219
221 #include <assert.h>
222 #include <libpmemkv.h>
223 #include <stdio.h>
224 #include <stdlib.h>
225 #include <string.h>
226 #define LOG(msg) puts(msg)
228 #define MAX_VAL_LEN 64
229 static const uint64_t SIZE = 1024UL * 1024UL * 1024UL;
231 int get_kv_callback(const char *k, size_t kb, const char *value, size_t value_bytes,
233 void *arg)
234 {
235 printf(" visited: %s\n", k);
236 return 0;
238 }
239 int main(int argc, char *argv[])
241 {
242 if (argc < 2) {
243 fprintf(stderr, "Usage: %s file\n", argv[0]);
244 exit(1);
245 }
246 /* See libpmemkv_config(3) for more detailed example of config creation */
248 LOG("Creating config");
249 pmemkv_config *cfg = pmemkv_config_new();
250 assert(cfg != NULL);
251 int s = pmemkv_config_put_string(cfg, "path", argv[1]);
253 assert(s == PMEMKV_STATUS_OK);
254 s = pmemkv_config_put_uint64(cfg, "size", SIZE);
255 assert(s == PMEMKV_STATUS_OK);
256 s = pmemkv_config_put_uint64(cfg, "force_create", 1);
257 assert(s == PMEMKV_STATUS_OK);
258 LOG("Opening pmemkv database with 'cmap' engine");
260 pmemkv_db *db = NULL;
261 s = pmemkv_open("cmap", cfg, &db);
262 assert(s == PMEMKV_STATUS_OK);
263 assert(db != NULL);
264 LOG("Putting new key");
266 const char *key1 = "key1";
267 const char *value1 = "value1";
268 s = pmemkv_put(db, key1, strlen(key1), value1, strlen(value1));
269 assert(s == PMEMKV_STATUS_OK);
270 size_t cnt;
272 s = pmemkv_count_all(db, &cnt);
273 assert(s == PMEMKV_STATUS_OK);
274 assert(cnt == 1);
275 LOG("Reading key back");
277 char val[MAX_VAL_LEN];
278 s = pmemkv_get_copy(db, key1, strlen(key1), val, MAX_VAL_LEN, NULL);
279 assert(s == PMEMKV_STATUS_OK);
280 assert(!strcmp(val, "value1"));
281 LOG("Iterating existing keys");
283 const char *key2 = "key2";
284 const char *value2 = "value2";
285 const char *key3 = "key3";
286 const char *value3 = "value3";
287 pmemkv_put(db, key2, strlen(key2), value2, strlen(value2));
288 pmemkv_put(db, key3, strlen(key3), value3, strlen(value3));
289 pmemkv_get_all(db, &get_kv_callback, NULL);
290 LOG("Removing existing key");
292 s = pmemkv_remove(db, key1, strlen(key1));
293 assert(s == PMEMKV_STATUS_OK);
294 assert(pmemkv_exists(db, key1, strlen(key1)) == PMEMKV_STATUS_NOT_FOUND);
295 LOG("Defragmenting the database");
297 s = pmemkv_defrag(db, 0, 100);
298 assert(s == PMEMKV_STATUS_OK);
299 LOG("Closing database");
301 pmemkv_close(db);
302 return 0;
304 }
305
307 libpmemkv(7), libpmemkv_config(3) and <https://pmem.io>
308PMEMKV - pmemkv version 1.1 2020-02-12 PMEMKV(3)