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 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 /**
24  * @defgroup batch_operations Batch Operations
25  * @ingroup client_operations
26  *
27  * Aerospike provides a batch API to access data in the cluster.
28  *
29  * The Batch API is a collection of APIs that use as_keyset as for looking up
30  * records for accessing in the cluster.
31  *
32  */
33 
34 #include <aerospike/aerospike.h>
35 #include <aerospike/as_batch.h>
36 #include <aerospike/as_error.h>
37 #include <aerospike/as_key.h>
38 #include <aerospike/as_list.h>
40 #include <aerospike/as_policy.h>
41 #include <aerospike/as_record.h>
42 #include <aerospike/as_status.h>
43 #include <aerospike/as_val.h>
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  * Test whether multiple records exist in the cluster.
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  * if ( aerospike_batch_exists(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
124  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
125  * }
126  *
127  * as_batch_destroy(&batch);
128  * ~~~~~~~~~~
129  *
130  * @param as The aerospike instance to use for this operation.
131  * @param err The as_error to be populated if an error occurs.
132  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
133  * @param batch The batch of keys to read.
134  * @param callback The callback to invoke for each record read.
135  * @param udata The user-data for the callback.
136  *
137  * @return AEROSPIKE_OK if successful. Otherwise an error.
138  *
139  * @ingroup batch_operations
140  */
142  aerospike * as, as_error * err, const as_policy_batch * policy,
143  const as_batch * batch,
144  aerospike_batch_read_callback callback, void * udata
145  );
146 
147 #ifdef __cplusplus
148 } // end extern "C"
149 #endif
as_status
Definition: as_status.h:30
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_exists(aerospike *as, as_error *err, const as_policy_batch *policy, const as_batch *batch, aerospike_batch_read_callback callback, void *udata)
bool(* aerospike_batch_read_callback)(const as_batch_read *results, uint32_t n, void *udata)