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 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 /******************************************************************************
46  * TYPES
47  *****************************************************************************/
48 
49 /**
50  * This callback will be called with the results of aerospike_batch_get(),
51  * or aerospike_batch_exists() functions.
52  *
53  * The `results` argument will be an array of `n` as_batch_read entries. The
54  * `results` argument is on the stack and is only available within the context
55  * of the callback. To use the data outside of the callback, copy the data.
56  *
57  * ~~~~~~~~~~{.c}
58  * bool my_callback(const as_batch_read * results, uint32_t n, void * udata) {
59  * return true;
60  * }
61  * ~~~~~~~~~~
62  *
63  * @param results The results from the batch request.
64  * @param n The number of results from the batch request.
65  * @param udata User-data provided to the calling function.
66  *
67  * @return `true` on success. Otherwise, an error occurred.
68  *
69  * @ingroup batch_operations
70  */
71 typedef bool (* aerospike_batch_read_callback)(const as_batch_read * results, uint32_t n, void * udata);
72 
73 /******************************************************************************
74  * FUNCTIONS
75  *****************************************************************************/
76 
77 /**
78  * Look up multiple records by key, then return all bins.
79  *
80  * ~~~~~~~~~~{.c}
81  * as_batch batch;
82  * as_batch_inita(&batch, 3);
83  *
84  * as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
85  * as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
86  * as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
87  *
88  * if ( aerospike_batch_get(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
89  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
90  * }
91  *
92  * as_batch_destroy(&batch);
93  * ~~~~~~~~~~
94  *
95  * @param as The aerospike instance to use for this operation.
96  * @param err The as_error to be populated if an error occurs.
97  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
98  * @param batch The batch of keys to read.
99  * @param callback The callback to invoke for each record read.
100  * @param udata The user-data for the callback.
101  *
102  * @return AEROSPIKE_OK if successful. Otherwise an error.
103  *
104  * @ingroup batch_operations
105  */
107  aerospike * as, as_error * err, const as_policy_batch * policy,
108  const as_batch * batch,
109  aerospike_batch_read_callback callback, void * udata
110  );
111 
112 /**
113  * Look up multiple records by key, then return specified bins.
114  *
115  * ~~~~~~~~~~{.c}
116  * as_batch batch;
117  * as_batch_inita(&batch, 3);
118  *
119  * as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
120  * as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
121  * as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
122  *
123  * const char* bin_filters[] = {"bin1", "bin2"};
124  *
125  * if ( aerospike_batch_get_bins(&as, &err, NULL, &batch, bin_filters, 2, callback, NULL) != AEROSPIKE_OK ) {
126  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
127  * }
128  *
129  * as_batch_destroy(&batch);
130  * ~~~~~~~~~~
131  *
132  * @param as The aerospike instance to use for this operation.
133  * @param err The as_error to be populated if an error occurs.
134  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
135  * @param batch The batch of keys to read.
136  * @param bins Bin filters. Only return these bins.
137  * @param n_bins The number of bin filters.
138  * @param callback The callback to invoke for each record read.
139  * @param udata The user-data for the callback.
140  *
141  * @return AEROSPIKE_OK if successful. Otherwise an error.
142  *
143  * @ingroup batch_operations
144  */
145 as_status
147  aerospike* as, as_error* err, const as_policy_batch* policy, const as_batch* batch,
148  const char** bins, uint32_t n_bins, aerospike_batch_read_callback callback, void* udata
149  );
150 
151 /**
152  * Test whether multiple records exist in the cluster.
153  *
154  * ~~~~~~~~~~{.c}
155  * as_batch batch;
156  * as_batch_inita(&batch, 3);
157  *
158  * as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
159  * as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
160  * as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
161  *
162  * if ( aerospike_batch_exists(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
163  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
164  * }
165  *
166  * as_batch_destroy(&batch);
167  * ~~~~~~~~~~
168  *
169  * @param as The aerospike instance to use for this operation.
170  * @param err The as_error to be populated if an error occurs.
171  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
172  * @param batch The batch of keys to read.
173  * @param callback The callback to invoke for each record read.
174  * @param udata The user-data for the callback.
175  *
176  * @return AEROSPIKE_OK if successful. Otherwise an error.
177  *
178  * @ingroup batch_operations
179  */
181  aerospike * as, as_error * err, const as_policy_batch * policy,
182  const as_batch * batch,
183  aerospike_batch_read_callback callback, void * udata
184  );
185 
186 #ifdef __cplusplus
187 } // end extern "C"
188 #endif