sdskv-client.h 9.52 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
/**
 * @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
154
155
156
        sdskv_database_id_t db_id, const void *key,
        hg_size_t ksize);

157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
/**
 * 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
182
183
int sdskv_list_keys(
        sdskv_provider_handle_t provider,
184
185
186
187
188
189
        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
190

191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
/**
 * @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
209
210
int sdskv_list_keys_with_prefix(
        sdskv_provider_handle_t provider,
211
212
213
214
        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
215
        hg_size_t prefix_size,
216
217
218
        void **keys,
        hg_size_t* ksizes, 
        hg_size_t* max_keys);
Matthieu Dorier's avatar
Matthieu Dorier committed
219

220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
/**
 * @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
239
240
241
242
243
244
245
246
247
248
249
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);

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
/**
 * @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
268
269
270
271
272
273
274
275
276
277
278
279
280
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);

Matthieu Dorier's avatar
Matthieu Dorier committed
281
282
283
284
285
286
/**
 * 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 
287
288
 *
 * @return SDSKV_SUCCESS or error code defined in sdskv-common.h
Matthieu Dorier's avatar
Matthieu Dorier committed
289
290
291
292
 */
int sdskv_shutdown_service(
        sdskv_client_t client, hg_addr_t addr);

Matthieu Dorier's avatar
Matthieu Dorier committed
293
294
295
296
297
#if defined(__cplusplus)
}
#endif

#endif