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_batch_read_record*)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  * 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
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
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
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
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
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
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