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-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
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 #pragma once
35 
36 #include <aerospike/aerospike.h>
37 #include <aerospike/as_batch.h>
38 #include <aerospike/as_error.h>
39 #include <aerospike/as_key.h>
40 #include <aerospike/as_list.h>
42 #include <aerospike/as_policy.h>
43 #include <aerospike/as_record.h>
44 #include <aerospike/as_status.h>
45 #include <aerospike/as_val.h>
46 
47 /******************************************************************************
48  * TYPES
49  *****************************************************************************/
50 
51 /**
52  * This callback will be called with the results of aerospike_batch_get(),
53  * or aerospike_batch_exists() functions.
54  *
55  * The `results` argument will be an array of `n` as_batch_read entries. The
56  * `results` argument is on the stack and is only available within the context
57  * of the callback. To use the data outside of the callback, copy the data.
58  *
59  * ~~~~~~~~~~{.c}
60  * bool my_callback(const as_batch_read * results, uint32_t n, void * udata) {
61  * return true;
62  * }
63  * ~~~~~~~~~~
64  *
65  * @param results The results from the batch request.
66  * @param n The number of results from the batch request.
67  * @param udata User-data provided to the calling function.
68  *
69  * @return `true` on success. Otherwise, an error occurred.
70  *
71  * @ingroup batch_operations
72  */
73 typedef bool (* aerospike_batch_read_callback)(const as_batch_read * results, uint32_t n, void * udata);
74 
75 /******************************************************************************
76  * FUNCTIONS
77  *****************************************************************************/
78 
79 /**
80  * Look up multiple records by key, then return all bins.
81  *
82  * ~~~~~~~~~~{.c}
83  * as_batch batch;
84  * as_batch_inita(&batch, 3);
85  *
86  * as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
87  * as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
88  * as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
89  *
90  * if ( aerospike_batch_get(&as, &err, NULL, &batch, callback, NULL) != AEROSPIKE_OK ) {
91  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
92  * }
93  *
94  * as_batch_destroy(&batch);
95  * ~~~~~~~~~~
96  *
97  * @param as The aerospike instance to use for this operation.
98  * @param err The as_error to be populated if an error occurs.
99  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
100  * @param batch The batch of keys to read.
101  * @param callback The callback to invoke for each record read.
102  * @param udata The user-data for the callback.
103  *
104  * @return AEROSPIKE_OK if successful. Otherwise an error.
105  *
106  * @ingroup batch_operations
107  */
109  aerospike * as, as_error * err, const as_policy_batch * policy,
110  const as_batch * batch,
111  aerospike_batch_read_callback callback, void * udata
112  );
113 
114 /**
115  * Test whether multiple records exist in the cluster.
116  *
117  * ~~~~~~~~~~{.c}
118  * as_batch batch;
119  * as_batch_inita(&batch, 3);
120  *
121  * as_key_init(as_batch_keyat(&batch,0), "ns", "set", "key1");
122  * as_key_init(as_batch_keyat(&batch,1), "ns", "set", "key2");
123  * as_key_init(as_batch_keyat(&batch,2), "ns", "set", "key3");
124  *
125  * if ( aerospike_batch_exists(&as, &err, NULL, &batch, 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 callback The callback to invoke for each record read.
137  * @param udata The user-data for the callback.
138  *
139  * @return AEROSPIKE_OK if successful. Otherwise an error.
140  *
141  * @ingroup batch_operations
142  */
144  aerospike * as, as_error * err, const as_policy_batch * policy,
145  const as_batch * batch,
146  aerospike_batch_read_callback callback, void * udata
147  );