Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
aerospike_batch.h
Go to the documentation of this file.
1
/*
2
* Copyright 2008-2015 Aerospike, Inc.
3
*
4
* Portions may be licensed to Aerospike, Inc. under one or more contributor
5
* license agreements.
6
*
7
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
8
* use this file except in compliance with the License. You may obtain a copy of
9
* the License at http://www.apache.org/licenses/LICENSE-2.0
10
*
11
* Unless required by applicable law or agreed to in writing, software
12
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
* License for the specific language governing permissions and limitations under
15
* the License.
16
*/
17
#pragma once
18
19
/**
20
* @defgroup batch_operations Batch Operations
21
* @ingroup client_operations
22
*
23
* Aerospike provides a batch API to access data in the cluster.
24
*
25
* The Batch API is a collection of APIs that use as_keyset as for looking up
26
* records for accessing in the cluster.
27
*
28
*/
29
30
#include <
aerospike/aerospike.h
>
31
#include <
aerospike/as_batch.h
>
32
#include <
aerospike/as_error.h
>
33
#include <
aerospike/as_key.h
>
34
#include <
aerospike/as_list.h
>
35
#include <
aerospike/as_operations.h
>
36
#include <
aerospike/as_policy.h
>
37
#include <
aerospike/as_record.h
>
38
#include <
aerospike/as_status.h
>
39
#include <
aerospike/as_val.h
>
40
#include <
aerospike/as_vector.h
>
41
42
#ifdef __cplusplus
43
extern
"C"
{
44
#endif
45
46
/******************************************************************************
47
* TYPES
48
*****************************************************************************/
49
50
/**
51
* Key and bin names used in batch commands where variables bins are needed for each key.
52
* The returned records are located in the same batch record.
53
*/
54
typedef
struct
as_batch_read_record_s {
55
/**
56
* The key requested.
57
*/
58
as_key
key
;
59
60
/**
61
* Bin names requested for this key.
62
*/
63
char
**
bin_names
;
64
65
/**
66
* Count of bin names requested for this key.
67
*/
68
uint32_t
n_bin_names
;
69
70
/**
71
* If true, ignore bin_names and read all bins.
72
* If false and bin_names are set, read specified bin_names.
73
* If false and bin_names are not set, read record header (generation, expiration) only.
74
*/
75
bool
read_all_bins
;
76
77
/**
78
* The result of the read transaction.
79
* <p>
80
* Values:
81
* <ul>
82
* <li>
83
* AEROSPIKE_OK: record found
84
* </li>
85
* <li>
86
* AEROSPIKE_ERR_RECORD_NOT_FOUND: record not found
87
* </li>
88
* <li>
89
* Other: transaction error code
90
* </li>
91
* </ul>
92
*/
93
as_status
result
;
94
95
/**
96
* The record for the key requested. For "exists" calls, the record will never contain bins
97
* but will contain metadata (generation and expiration) when the record exists.
98
*/
99
as_record
record
;
100
}
as_batch_read_record
;
101
102
/**
103
* List of as_batch_read_record(s).
104
*/
105
typedef
struct
as_batch_read_records_s {
106
/**
107
* List of as_batch_read_record(s).
108
*/
109
as_vector
list
;
110
}
as_batch_read_records
;
111
112
/**
113
* This callback will be called with the results of aerospike_batch_get(),
114
* or aerospike_batch_exists() functions.
115
*
116
* The `results` argument will be an array of `n` as_batch_read entries. The
117
* `results` argument is on the stack and is only available within the context
118
* of the callback. To use the data outside of the callback, copy the data.
119
*
120
* ~~~~~~~~~~{.c}
121
* bool my_callback(const as_batch_read * results, uint32_t n, void * udata) {
122
* return true;
123
* }
124
* ~~~~~~~~~~
125
*
126
* @param results The results from the batch request.
127
* @param n The number of results from the batch request.
128
* @param udata User-data provided to the calling function.
129
*
130
* @return `true` on success. Otherwise, an error occurred.
131
*
132
* @ingroup batch_operations
133
*/
134
typedef
bool (*
aerospike_batch_read_callback
)(
const
as_batch_read
* results, uint32_t n,
void
* udata);
135
136
137
/**
138
* @private
139
* This callback is used by aerospike_batch_get_xdr() to send one batch record at a time
140
* as soon as they are received in no particular order.
141
*/
142
typedef
bool (*
as_batch_callback_xdr
)(
as_key
* key,
as_record
* record,
void
* udata);
143
144
/******************************************************************************
145
* FUNCTIONS
146
*****************************************************************************/
147
148
/**
149
* Initialize `as_batch_read_records` with specified capacity on the stack using alloca().
150
*
151
* When the batch is no longer needed, then use as_batch_destroy() to
152
* release the batch and associated resources.
153
*
154
* @param __records Batch record list.
155
* @param __capacity Initial capacity of batch record list. List will resize when necessary.
156
*
157
* @relates as_batch_read_record
158
* @ingroup batch_operations
159
*/
160
#define as_batch_read_inita(__records, __capacity) \
161
as_vector_inita(&((__records)->list), sizeof(as_batch_read_record), __capacity);
162
163
/**
164
* Initialize `as_batch_read_records` with specified capacity on the heap.
165
*
166
* When the batch is no longer needed, then use as_batch_destroy() to
167
* release the batch and associated resources.
168
*
169
* @param records Batch record list.
170
* @param capacity Initial capacity of batch record list. List will resize when necessary.
171
*
172
* @relates as_batch_read_record
173
* @ingroup batch_operations
174
*/
175
static
inline
void
176
as_batch_read_init
(
as_batch_read_records
* records, uint32_t capacity)
177
{
178
as_vector_init
(&records->
list
,
sizeof
(
as_batch_read_record
), capacity);
179
}
180
181
/**
182
* Reserve a new `as_batch_read_record` slot. Capacity will be increased when necessary.
183
* Return reference to record. The record is already initialized to zeroes.
184
*
185
* @param records Batch record list.
186
*
187
* @relates as_batch_read_record
188
* @ingroup batch_operations
189
*/
190
static
inline
as_batch_read_record
*
191
as_batch_read_reserve
(
as_batch_read_records
* records)
192
{
193
return
as_vector_reserve
(&records->
list
);
194
}
195
196
/**
197
* Destroy keys and records in record list. It's the responsility of the caller to
198
* free `as_batch_read_record.bin_names` when necessary.
199
*
200
* @param records Batch record list.
201
*
202
* @relates as_batch_read_record
203
* @ingroup batch_operations
204
*/
205
void
206
as_batch_read_destroy
(
as_batch_read_records
* records);
207
208
/**
209
* Do the connected servers support the new batch index protocol.
210
* The cluster must already be connected (aerospike_connect()) prior to making this call.
211
*/
212
bool
213
aerospike_has_batch_index
(
aerospike
* as);
214
215
/**
216
* Read multiple records for specified batch keys in one batch call.
217
* This method allows different namespaces/bins to be requested for each key in the batch.
218
* The returned records are located in the same batch array.
219
* This method requires Aerospike Server version >= 3.6.0.
220
*
221
* ~~~~~~~~~~{.c}
222
* as_batch_read_records records;
223
* as_batch_read_inita(&records, 10);
224
*
225
* char* bin_names[] = {"bin1", "bin2"};
226
* char* ns = "ns";
227
* char* set = "set";
228
*
229
* as_batch_read_record* record = as_batch_read_reserve(&records);
230
* as_key_init(&record->key, ns, set, "key1");
231
* record->bin_names = bin_names;
232
* record->n_bin_names = 2;
233
*
234
* record = as_batch_read_reserve(&records);
235
* as_key_init(&record->key, ns, set, "key2");
236
* record->read_all_bins = true;
237
*
238
* if (aerospike_batch_read(&as, &err, NULL, &records) != AEROSPIKE_OK) {
239
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
240
* }
241
*
242
* as_batch_read_destroy(&records);
243
* ~~~~~~~~~~
244
*
245
* @param as The aerospike instance to use for this operation.
246
* @param err The as_error to be populated if an error occurs.
247
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
248
* @param records List of keys and bins to retrieve.
249
* The returned records are located in the same array.
250
*
251
* @return AEROSPIKE_OK if successful. Otherwise an error.
252
*
253
* @ingroup batch_operations
254
*/
255
as_status
256
aerospike_batch_read
(
257
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
as_batch_read_records
* records
258
);
259
260
/**
261
* Look up multiple records by key, then return all bins.
262
*
263
* ~~~~~~~~~~{.c}
264
* as_batch batch;
265
* as_batch_inita(&batch, 3);
266
*
267
* as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
268
* as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
269
* as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
270
*
271
* if ( aerospike_batch_get(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
272
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
273
* }
274
*
275
* as_batch_destroy(&batch);
276
* ~~~~~~~~~~
277
*
278
* @param as The aerospike instance to use for this operation.
279
* @param err The as_error to be populated if an error occurs.
280
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
281
* @param batch The batch of keys to read.
282
* @param callback The callback to invoke for each record read.
283
* @param udata The user-data for the callback.
284
*
285
* @return AEROSPIKE_OK if successful. Otherwise an error.
286
*
287
* @ingroup batch_operations
288
*/
289
as_status
290
aerospike_batch_get
(
291
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
292
aerospike_batch_read_callback
callback,
void
* udata
293
);
294
295
/**
296
* @private
297
* Perform batch reads for XDR. The callback will be called for each record as soon as it's
298
* received in no particular order.
299
*/
300
as_status
301
aerospike_batch_get_xdr
(
302
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
303
as_batch_callback_xdr
callback,
void
* udata
304
);
305
306
/**
307
* Look up multiple records by key, then return specified bins.
308
*
309
* ~~~~~~~~~~{.c}
310
* as_batch batch;
311
* as_batch_inita(&batch, 3);
312
*
313
* as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
314
* as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
315
* as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
316
*
317
* const char* bin_filters[] = {"bin1", "bin2"};
318
*
319
* if ( aerospike_batch_get_bins(&as, &err, NULL, &batch, bin_filters, 2, callback, NULL) != AEROSPIKE_OK ) {
320
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
321
* }
322
*
323
* as_batch_destroy(&batch);
324
* ~~~~~~~~~~
325
*
326
* @param as The aerospike instance to use for this operation.
327
* @param err The as_error to be populated if an error occurs.
328
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
329
* @param batch The batch of keys to read.
330
* @param bins Bin filters. Only return these bins.
331
* @param n_bins The number of bin filters.
332
* @param callback The callback to invoke for each record read.
333
* @param udata The user-data for the callback.
334
*
335
* @return AEROSPIKE_OK if successful. Otherwise an error.
336
*
337
* @ingroup batch_operations
338
*/
339
as_status
340
aerospike_batch_get_bins
(
341
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
342
const
char
** bins, uint32_t n_bins,
aerospike_batch_read_callback
callback,
void
* udata
343
);
344
345
/**
346
* Test whether multiple records exist in the cluster.
347
*
348
* ~~~~~~~~~~{.c}
349
* as_batch batch;
350
* as_batch_inita(&batch, 3);
351
*
352
* as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
353
* as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
354
* as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
355
*
356
* if ( aerospike_batch_exists(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
357
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
358
* }
359
*
360
* as_batch_destroy(&batch);
361
* ~~~~~~~~~~
362
*
363
* @param as The aerospike instance to use for this operation.
364
* @param err The as_error to be populated if an error occurs.
365
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
366
* @param batch The batch of keys to read.
367
* @param callback The callback to invoke for each record read.
368
* @param udata The user-data for the callback.
369
*
370
* @return AEROSPIKE_OK if successful. Otherwise an error.
371
*
372
* @ingroup batch_operations
373
*/
374
as_status
375
aerospike_batch_exists
(
376
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
377
aerospike_batch_read_callback
callback,
void
* udata
378
);
379
380
#ifdef __cplusplus
381
}
// end extern "C"
382
#endif