All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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  */
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  */
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  */
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  */
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  */
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*
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
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
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
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
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
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
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
void as_vector_init(as_vector *vector, uint32_t item_size, uint32_t capacity)
static void * as_vector_reserve(as_vector *vector)
Definition: as_vector.h:166
as_status aerospike_batch_read(aerospike *as, as_error *err, const as_policy_batch *policy, as_batch_read_records *records)
as_status
Definition: as_status.h:30
static void as_batch_read_init(as_batch_read_records *records, uint32_t capacity)
as_status aerospike_batch_get_xdr(aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, as_batch_callback_xdr callback, void *udata)
as_status aerospike_batch_get(aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, aerospike_batch_read_callback callback, void *udata)
as_status aerospike_batch_get_bins(aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, const char **bins, uint32_t n_bins, aerospike_batch_read_callback callback, void *udata)
as_status aerospike_batch_exists(aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, aerospike_batch_read_callback callback, void *udata)
static as_batch_read_record * as_batch_read_reserve(as_batch_read_records *records)
void as_batch_read_destroy(as_batch_read_records *records)
Definition: as_key.h:199
bool(* aerospike_batch_read_callback)(const as_batch_read *results, uint32_t n, void *udata)
bool(* as_batch_callback_xdr)(as_key *key, as_record *record, void *udata)