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
* Read multiple records for specified batch keys in one batch call.
210
* This method allows different namespaces/bins to be requested for each key in the batch.
211
* The returned records are located in the same batch array.
212
* This method requires Aerospike Server version >= 3.5.15.
213
*
214
* ~~~~~~~~~~{.c}
215
* as_batch_read_records records;
216
* as_batch_read_inita(&records, 10);
217
*
218
* char* bin_names[] = {"bin1", "bin2"};
219
* char* ns = "ns";
220
* char* set = "set";
221
*
222
* as_batch_read_record* record = as_batch_read_reserve(&records);
223
* as_key_init(&record->key, ns, set, "key1");
224
* record->bin_names = bin_names;
225
* record->n_bin_names = 2;
226
*
227
* record = as_batch_read_reserve(&records);
228
* as_key_init(&record->key, ns, set, "key2");
229
* record->read_all_bins = true;
230
*
231
* if (aerospike_batch_read(&as, &err, NULL, &records) != AEROSPIKE_OK) {
232
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
233
* }
234
*
235
* as_batch_read_destroy(&records);
236
* ~~~~~~~~~~
237
*
238
* @param as The aerospike instance to use for this operation.
239
* @param err The as_error to be populated if an error occurs.
240
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
241
* @param records List of keys and bins to retrieve.
242
* The returned records are located in the same array.
243
*
244
* @return AEROSPIKE_OK if successful. Otherwise an error.
245
*
246
* @ingroup batch_operations
247
*/
248
as_status
249
aerospike_batch_read
(
250
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
as_batch_read_records
* records
251
);
252
253
/**
254
* Look up multiple records by key, then return all bins.
255
*
256
* ~~~~~~~~~~{.c}
257
* as_batch batch;
258
* as_batch_inita(&batch, 3);
259
*
260
* as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
261
* as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
262
* as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
263
*
264
* if ( aerospike_batch_get(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
265
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
266
* }
267
*
268
* as_batch_destroy(&batch);
269
* ~~~~~~~~~~
270
*
271
* @param as The aerospike instance to use for this operation.
272
* @param err The as_error to be populated if an error occurs.
273
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
274
* @param batch The batch of keys to read.
275
* @param callback The callback to invoke for each record read.
276
* @param udata The user-data for the callback.
277
*
278
* @return AEROSPIKE_OK if successful. Otherwise an error.
279
*
280
* @ingroup batch_operations
281
*/
282
as_status
283
aerospike_batch_get
(
284
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
285
aerospike_batch_read_callback
callback,
void
* udata
286
);
287
288
/**
289
* @private
290
* Perform batch reads for XDR. The callback will be called for each record as soon as it's
291
* received in no particular order.
292
*/
293
as_status
294
aerospike_batch_get_xdr
(
295
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
296
as_batch_callback_xdr
callback,
void
* udata
297
);
298
299
/**
300
* Look up multiple records by key, then return specified bins.
301
*
302
* ~~~~~~~~~~{.c}
303
* as_batch batch;
304
* as_batch_inita(&batch, 3);
305
*
306
* as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
307
* as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
308
* as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
309
*
310
* const char* bin_filters[] = {"bin1", "bin2"};
311
*
312
* if ( aerospike_batch_get_bins(&as, &err, NULL, &batch, bin_filters, 2, callback, NULL) != AEROSPIKE_OK ) {
313
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
314
* }
315
*
316
* as_batch_destroy(&batch);
317
* ~~~~~~~~~~
318
*
319
* @param as The aerospike instance to use for this operation.
320
* @param err The as_error to be populated if an error occurs.
321
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
322
* @param batch The batch of keys to read.
323
* @param bins Bin filters. Only return these bins.
324
* @param n_bins The number of bin filters.
325
* @param callback The callback to invoke for each record read.
326
* @param udata The user-data for the callback.
327
*
328
* @return AEROSPIKE_OK if successful. Otherwise an error.
329
*
330
* @ingroup batch_operations
331
*/
332
as_status
333
aerospike_batch_get_bins
(
334
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
335
const
char
** bins, uint32_t n_bins,
aerospike_batch_read_callback
callback,
void
* udata
336
);
337
338
/**
339
* Test whether multiple records exist in the cluster.
340
*
341
* ~~~~~~~~~~{.c}
342
* as_batch batch;
343
* as_batch_inita(&batch, 3);
344
*
345
* as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
346
* as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
347
* as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
348
*
349
* if ( aerospike_batch_exists(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
350
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
351
* }
352
*
353
* as_batch_destroy(&batch);
354
* ~~~~~~~~~~
355
*
356
* @param as The aerospike instance to use for this operation.
357
* @param err The as_error to be populated if an error occurs.
358
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
359
* @param batch The batch of keys to read.
360
* @param callback The callback to invoke for each record read.
361
* @param udata The user-data for the callback.
362
*
363
* @return AEROSPIKE_OK if successful. Otherwise an error.
364
*
365
* @ingroup batch_operations
366
*/
367
as_status
368
aerospike_batch_exists
(
369
aerospike
* as,
as_error
* err,
const
as_policy_batch
* policy,
const
as_batch
* batch,
370
aerospike_batch_read_callback
callback,
void
* udata
371
);
372
373
#ifdef __cplusplus
374
}
// end extern "C"
375
#endif