sdskv-client.h 15.9 KB
Newer Older
Matthieu Dorier's avatar
Matthieu Dorier committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#ifndef sds_keyval_client_h
#define sds_keyval_client_h

#include <margo.h>
#include <stdint.h>
#include <sdskv-common.h>

#if defined(__cplusplus)
extern "C" {
#endif

typedef struct sdskv_client* sdskv_client_t;
#define SDSKV_CLIENT_NULL ((sdskv_client_t)NULL)

typedef struct sdskv_provider_handle *sdskv_provider_handle_t;
#define SDSKV_PROVIDER_HANDLE_NULL ((sdskv_provider_handle_t)NULL)

18
19
20
21
22
23
24
25
/**
 * @brief Creates a SDSKV client.
 *
 * @param[in] mid Margo instance
 * @param[out] client SDSKV client
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
26
27
int sdskv_client_init(margo_instance_id mid, sdskv_client_t* client);

28
29
30
31
32
33
34
/**
 * @brief Finalizes a SDSKV client.
 *
 * @param[in] client SDSKV client to finalize
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
35
36
int sdskv_client_finalize(sdskv_client_t client);

37
38
39
40
41
/**
 * @brief Creates a SDSKV provider handle.
 *
 * @param[in] client SDSKV client responsible for the provider handle
 * @param[in] addr Mercury address of the provider
42
 * @param[in] provider_id id of the provider
43
44
45
46
 * @param[in] handle provider handle
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
47
48
49
int sdskv_provider_handle_create(
        sdskv_client_t client,
        hg_addr_t addr,
50
        uint16_t provider_id,
Matthieu Dorier's avatar
Matthieu Dorier committed
51
52
        sdskv_provider_handle_t* handle);

53
54
55
56
57
58
59
/**
 * @brief Increments the reference counter of a provider handle.
 *
 * @param handle provider handle
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
60
61
62
int sdskv_provider_handle_ref_incr(
        sdskv_provider_handle_t handle);

63
64
65
66
67
68
69
70
71
/**
 * @brief Releases the provider handle. This will decrement the
 * reference counter, and free the provider handle if the reference
 * counter reaches 0.
 *
 * @param[in] handle provider handle to release.
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
72
int sdskv_provider_handle_release(sdskv_provider_handle_t handle);
Matthieu Dorier's avatar
Matthieu Dorier committed
73

74
75
76
77
78
79
80
81
82
83
84
/**
 * @brief Opens a database. This effectively contacts the provider
 * pointed to by the provider handle and request the database id
 * associated with the database name.
 *
 * @param[in] provider provider handle
 * @param[in] db_name name of the database to lookup
 * @param[out] db_id database id
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
85
86
87
88
89
int sdskv_open(
        sdskv_provider_handle_t provider,
        const char* db_name,
        sdskv_database_id_t* db_id);

90
91
92
93
94
95
96
97
98
99
100
101
/**
 * @brief Puts a key/value pair into the database.
 *
 * @param provider provider handle managing the database
 * @param db_id targeted database id
 * @param key key to store
 * @param ksize size (in bytes) of the key
 * @param value value to store
 * @param vsize size (in bytes) of the value
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
102
103
104
105
106
int sdskv_put(sdskv_provider_handle_t provider, 
        sdskv_database_id_t db_id,
        const void *key, hg_size_t ksize,
        const void *value, hg_size_t vsize);

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
/**
 * @brief Gets the value associated with a given key.
 * vsize needs to be set to the current size of the allocated
 * value buffer. After a succesful call to sdskv_get, vsize
 * will hold the actual size of the key. Note that the size
 * of a value can get obtained using sdskv_length.
 *
 * @param[in] provider provider handle
 * @param[in] db_id database id of the target database
 * @param[in] key key to lookup
 * @param[in] ksize size of the key
 * @param[out] value pointer to buffer to put the value
 * @param[inout] vsize size of the value
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
123
124
125
126
127
int sdskv_get(sdskv_provider_handle_t provider,
        sdskv_database_id_t db_id, 
        const void *key, hg_size_t ksize,
        void *value, hg_size_t* vsize);

128
129
130
131
132
133
134
135
136
137
138
139
/**
 * @brief Gets the length of a value associated with a given key.
 *
 * @param[in] handle provider handle
 * @param[in] db_id database id
 * @param[in] key key to lookup
 * @param[in] ksize size of the key
 * @param[out] vsize size of the associated value
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_length(sdskv_provider_handle_t handle, 
Matthieu Dorier's avatar
Matthieu Dorier committed
140
141
142
        sdskv_database_id_t db_id, const void *key, 
        hg_size_t ksize, hg_size_t* vsize);

143
144
145
146
147
148
149
150
151
152
153
154
155
156
/**
 * @brief Checks if the given key exists in the database.
 *
 * @param[in] handle provider handle
 * @param[in] db_id database id
 * @param[in] key key to lookup
 * @param[in] ksize size of the key
 * @param[out] flag 1 if the key exists, 0 otherwise
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_exists(sdskv_provider_handle_t handle,
        sdskv_database_id_t db_id, const void *key,
        hg_size_t ksize, int* flag);
157
158
159
160
161
162
163
164
165
166
167
/**
 * @brief Erases the key/value pair pointed by the given key.
 *
 * @param handle provider handle
 * @param db_id database id
 * @param key key to erase
 * @param ksize size of the key
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_erase(sdskv_provider_handle_t handle,
Matthieu Dorier's avatar
Matthieu Dorier committed
168
169
170
        sdskv_database_id_t db_id, const void *key,
        hg_size_t ksize);

171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
/**
 * Lists at most max_keys keys starting strictly after start_key,
 * whether start_key is effectively in the database or not. "strictly after"
 * must be understood in the sens of the custom comparison function set
 * for the target database, if such comparison function has been set.
 * Passing NULL as start_key allows one to start listing from the beginning
 * of the database.
 * keys must be an array of max_keys void* elements, each element keys[i]
 * being a preallocated buffer of size ksizes[i]. ksizes must be an array
 * of sizes of the preallocated buffers. After a successful call, max_keys
 * is set to the actual number of keys retrieved, ksizes[i] is set to the
 * actual size of the i-th key, and keys[i] contains the i-th key. The call
 * will fail if at least one of the preallocated size is too small to hold
 * the key.
 *
 * @param[in] provider provider handle
 * @param[in] db_id database id
 * @param[in] start_key starting key
 * @param[in] start_ksize size of the starting key
 * @param[out] keys array of buffers to hold returned keys
 * @param[inout] ksizes array of key sizes
 * @param[inout] max_keys max keys requested
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
196
197
int sdskv_list_keys(
        sdskv_provider_handle_t provider,
198
199
200
201
202
203
        sdskv_database_id_t db_id,
        const void *start_key,
        hg_size_t start_ksize,
        void **keys,
        hg_size_t* ksizes,
        hg_size_t* max_keys);
Matthieu Dorier's avatar
Matthieu Dorier committed
204

205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
/**
 * @brief Same as sdskv_list_keys, but provides a prefix
 * that returned keys must start with. Note that "prefix" is understood
 * in the sens of the bytes making up the key, not in the sens of any
 * comparison function set by the user on the provider side.
 *
 * @param[in] provider provider handle
 * @param[in] db_id database id
 * @param[in] start_key starting key
 * @param[in] start_ksize size of the starting key
 * @param[in] prefix prefix that returned keys must match
 * @param[in] prefix_size size of the prefix
 * @param[out] keys array of buffers to hold returned keys
 * @param[inout] ksizes array of key sizes
 * @param[inout] max_keys max keys requested
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
223
224
int sdskv_list_keys_with_prefix(
        sdskv_provider_handle_t provider,
225
226
227
228
        sdskv_database_id_t db_id,
        const void *start_key,
        hg_size_t start_ksize,
        const void *prefix,
Matthieu Dorier's avatar
Matthieu Dorier committed
229
        hg_size_t prefix_size,
230
231
232
        void **keys,
        hg_size_t* ksizes, 
        hg_size_t* max_keys);
Matthieu Dorier's avatar
Matthieu Dorier committed
233

234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
/**
 * @brief Same as sdskv_list_keys but returns also the values.
 * The values array must be an array of max_keys sizes, with
 * each element values[i] being a buffer of size vsizes[i].
 * After a successful call, values[i] will hold the i-th value
 * and vsizes[i] will be set to the actual size of the i-th value.
 *
 * @param[in] provider provider handle
 * @param[in] db_id database id
 * @param[in] start_key starting key
 * @param[in] start_ksize size of the starting key
 * @param[out] keys array of buffers to hold returned keys
 * @param[inout] ksizes array of key sizes
 * @param[inout] values array of buffers to hold returned values
 * @param[inout] vsizes array of value sizes
 * @param[inout] max_keys max keys requested
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
253
254
255
256
257
258
259
260
261
262
263
int sdskv_list_keyvals(
        sdskv_provider_handle_t provider,
        sdskv_database_id_t db_id,
        const void *start_key,
        hg_size_t start_ksize,
        void **keys,
        hg_size_t* ksizes,
        void **values,
        hg_size_t* vsizes,
        hg_size_t* max_items);

264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
/**
 * @brief Same as sdskv_list_keyvals but lets the user provide
 * a prefix that returned keys must satisfy.
 *
 * @param[in] provider provider handle
 * @param[in] db_id database id
 * @param[in] start_key starting key
 * @param[in] start_ksize size of the starting key
 * @param[in] prefix prefix that returned keys must match
 * @param[in] prefix_size size of the prefix
 * @param[out] keys array of buffers to hold returned keys
 * @param[inout] ksizes array of key sizes
 * @param[inout] values array of buffers to hold returned values
 * @param[inout] vsizes array of value sizes
 * @param[inout] max_keys max keys requested
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
Matthieu Dorier's avatar
Matthieu Dorier committed
282
283
284
285
286
287
288
289
290
291
292
293
294
int sdskv_list_keyvals_with_prefix(
        sdskv_provider_handle_t provider,
        sdskv_database_id_t db_id,
        const void *start_key,
        hg_size_t start_ksize,
        const void *prefix,
        hg_size_t prefix_size,
        void **keys,
        hg_size_t* ksizes,
        void **values,
        hg_size_t* vsizes,
        hg_size_t* max_items);

295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
/**
 * @brief Migrates a set of keys/values from a source provider/database
 * to a target provider/database.
 *
 * @param source_provider source provider
 * @param source_db_id source database id
 * @param target_addr target address
 * @param target_provider_id target provider id
 * @param target_db_id target database id
 * @param num_keys number of keys
 * @param keys array of keys
 * @param key_sizes array of key sizes
 * @param flag SDSKV_KEEP_ORIGINAL, or SDSKV_REMOVE_BEFORE, or SDSKV_REMOVE_AFTER
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_migrate_keys(
        sdskv_provider_handle_t source_provider,
        sdskv_database_id_t source_db_id,
        const char* target_addr,
        uint16_t target_provider_id,
        sdskv_database_id_t target_db_id,
        hg_size_t num_keys,
        const void** keys,
        const hg_size_t* key_sizes,
        int flag);

/**
 * @brief Migrates a single key/value from a source provider/database
 * to a target provider/database.
 *
 * @param source_provider source provider
 * @param source_db_id source database id
 * @param target_addr target address
 * @param target_provider_id target provider id
 * @param target_db_id target database id
 * @param key key to migrate
 * @param key_size size of the key 
 * @param flag SDSKV_KEEP_ORIGINAL, or SDSKV_REMOVE_BEFORE, or SDSKV_REMOVE_AFTER
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
inline int sdskv_migrate_key(
        sdskv_provider_handle_t source_provider,
        sdskv_database_id_t source_db_id,
        const char* target_addr,
        uint16_t target_provider_id,
        sdskv_database_id_t target_db_id,
        const void* key,
        hg_size_t key_size,
        int flag)
{
    return sdskv_migrate_keys(
            source_provider,
            source_db_id,
            target_addr,
            target_provider_id,
            target_db_id,
            1,
            &key,
            &key_size,
            flag);
}

/**
 * @brief Migrates a set of keys/values from a source provider/database
 * to a target provider/database based on a range. The range is
 * expressed by the array key_range, which contains two elements.
 * key_range[0] must be a lower bound lb.
 * key_range[1] must be an upper bound ub.
 * The set of keys migrated are within the range [lb, ub[ (i.e. lb
 * included, ub is not included).
 *
 * @param source_provider source provider
 * @param source_db_id source database id
 * @param target_addr target address
 * @param target_provider_id target provider id
 * @param target_db_id target database id
 * @param key_range range of keys to migrate
 * @param key_range_sizes size of the keys provided for the range 
 * @param flag SDSKV_KEEP_ORIGINAL, or SDSKV_REMOVE_BEFORE, or SDSKV_REMOVE_AFTER
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_migrate_key_range(
        sdskv_provider_handle_t source_provider,
        sdskv_database_id_t source_db_id,
        const char* target_addr,
        uint16_t target_provider_id,
        sdskv_database_id_t target_db_id,
        const void* key_range[],
        const hg_size_t key_range_sizes[],
        int flag);

/**
 * @brief Migrates a set of keys/values from a source provider/database
 * to a target provider/database based on a prefix. 
 * All key matching the provided prefix will be migrated.
 *
 * @param source_provider source provider
 * @param source_db_id source database id
 * @param target_addr target address
 * @param target_provider_id target provider id
 * @param target_db_id target database id
 * @param key_prefix prefix of keys to migrate
 * @param key_prefix_size size of the prefix provided 
 * @param flag SDSKV_KEEP_ORIGINAL, or SDSKV_REMOVE_BEFORE, or SDSKV_REMOVE_AFTER
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_migrate_keys_prefixed(
        sdskv_provider_handle_t source_provider,
        sdskv_database_id_t source_db_id,
        const char* target_addr,
        uint16_t target_provider_id,
        sdskv_database_id_t target_db_id,
        const void* key_prefix,
        hg_size_t key_prefix_size,
        int flag);

/**
 * @brief Migrates all the keys/values from a source provider/database
 * to a target provider/database based on a prefix. 
 *
 * @param source_provider source provider
 * @param source_db_id source database id
 * @param target_addr target address
 * @param target_provider_id target provider id
 * @param target_db_id target database id
 * @param flag SDSKV_KEEP_ORIGINAL, or SDSKV_REMOVE_BEFORE, or SDSKV_REMOVE_AFTER
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_migrate_all_keys(
        sdskv_provider_handle_t source_provider,
        sdskv_database_id_t source_db_id,
        const char* target_addr,
        uint16_t target_provider_id,
        sdskv_database_id_t target_db_id,
        int flag);

/**
 * @brief Migrates a database from a source provider
 * to a target provider. The difference with sdskv_migrate_all_keys is
 * that the target database does not exist yet and the id of the newly
 * created database will be returned to the called.
 * Contrary to sdskv_migrate_all_keys, if SDSKV_REMOVE_BEFORE or
 * SDSKV_REMOVE_AFTER are used as flag, the source database is deleted
 * on its provider (while sdskv_migrate_all_keys only removes all the keys,
 * leaving the database present).
 *
 * @param source_provider source provider
 * @param source_db_id source database id
 * @param target_addr target address
 * @param target_provider_id target provider id
 * @param target_db_id resulting target database id
 * @param flag SDSKV_KEEP_ORIGINAL, or SDSKV_REMOVE_BEFORE, or SDSKV_REMOVE_AFTER
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
 */
int sdskv_migrate_database(
        sdskv_provider_handle_t source_provider,
        sdskv_database_id_t source_db_id,
        const char* target_addr,
        uint16_t target_provider_id,
        sdskv_database_id_t* target_db_id,
        int flag);

Matthieu Dorier's avatar
Matthieu Dorier committed
463
464
465
466
467
468
/**
 * Shuts down a remote SDSKV service (given an address).
 * This will shutdown all the providers on the target address.
 * 
 * @param [in] client SDSKV client
 * @param [in] addr address of the server 
469
470
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
Matthieu Dorier's avatar
Matthieu Dorier committed
471
472
473
474
 */
int sdskv_shutdown_service(
        sdskv_client_t client, hg_addr_t addr);

Matthieu Dorier's avatar
Matthieu Dorier committed
475
476
477
478
479
#if defined(__cplusplus)
}
#endif

#endif