All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_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 #pragma GCC diagnostic ignored "-Waddress"
20 
21 #include <aerospike/as_bin.h>
22 #include <aerospike/as_key.h>
23 #include <aerospike/as_record.h>
24 #include <aerospike/as_status.h>
25 #include <stdint.h>
26 #include <stdbool.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /*****************************************************************************
33  * STRUCTURES
34  *****************************************************************************/
35 
36 /**
37  * A collection of keys to be batch processed.
38  */
39 typedef struct as_batch_s {
40 
41  /**
42  * If true, then this structure will be freed when as_batch_destroy()
43  * is called.
44  */
45  bool _free;
46 
47  /**
48  * Sequence of keys in the batch.
49  */
50  struct {
51 
52  /**
53  * If true, then this structure will be freed when as_batch_destroy()
54  * is called.
55  */
56  bool _free;
57 
58  /**
59  * The number of keys this structure contains.
60  */
61  uint32_t size;
62 
63  /**
64  * The keys contained by this batch.
65  */
67 
68  } keys;
69 
70 } as_batch;
71 
72 /**
73  * The (key, result, record) for an entry in a batch read.
74  * The result is AEROSPIKE_OK if the record is found,
75  * AEROSPIKE_ERR_RECORD_NOT_FOUND if the transaction succeeds but the record is
76  * not found, or another error code if the transaction fails.
77  * The record is NULL if either the transaction failed or the record does not
78  * exist. For aerospike_batch_exists() calls the record will never contain bins
79  * but will contain metadata (generation and expiration).
80  */
81 typedef struct as_batch_read_s {
82 
83  /**
84  * The key requested.
85  */
86  const as_key * key;
87 
88  /**
89  * The result of the transaction to read this key.
90  */
92 
93  /**
94  * The record for the key requested, NULL if the key was not found.
95  */
97 
99 
100 
101 /*********************************************************************************
102  * INSTANCE MACROS
103  *********************************************************************************/
104 
105 
106 /**
107  * Initializes `as_batch` with specified capacity using alloca().
108  *
109  * For heap allocation, use `as_batch_new()`.
110  *
111  * ~~~~~~~~~~{.c}
112  * as_batch batch;
113  * as_batch_inita(&batch, 2);
114  * as_key_init(as_batch_get(&batch, 0), "ns", "set", "key1");
115  * as_key_init(as_batch_get(&batch, 1), "ns", "set", "key2");
116  * ~~~~~~~~~~
117  *
118  * When the batch is no longer needed, then use as_batch_destroy() to
119  * release the batch and associated resources.
120  *
121  * @param __batch The query to initialize.
122  * @param __size The number of keys to allocate.
123  *
124  * @relates as_batch
125  * @ingroup batch_object
126  */
127 #define as_batch_inita(__batch, __size) \
128  if ( (__batch) != NULL ) {\
129  (__batch)->_free = false;\
130  (__batch)->keys.entries = (as_key *) alloca(sizeof(as_key) * __size);\
131  if ( (__batch)->keys.entries ) { \
132  (__batch)->keys._free = false;\
133  (__batch)->keys.size = __size;\
134  }\
135  }
136 
137 /*********************************************************************************
138  * INSTANCE FUNCTIONS
139  *********************************************************************************/
140 
141 /**
142  * Create and initialize a heap allocated as_batch capable of storing
143  * `capacity` keys.
144  *
145  * ~~~~~~~~~~{.c}
146  * as_batch * batch = as_batch_new(2);
147  * as_key_init(as_batch_get(batch, 0), "ns", "set", "key1");
148  * as_key_init(as_batch_get(batch, 1), "ns", "set", "key2");
149  * ~~~~~~~~~~
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 size The number of keys to allocate.
155  *
156  * @relates as_batch
157  * @ingroup batch_object
158  */
159 as_batch * as_batch_new(uint32_t size);
160 
161 /**
162  * Initialize a stack allocated as_batch capable of storing `capacity` keys.
163  *
164  * ~~~~~~~~~~{.c}
165  * as_batch batch;
166  * as_batch_init(&batch, 2);
167  * as_key_init(as_batch_get(&batch, 0), "ns", "set", "key1");
168  * as_key_init(as_batch_get(&batch, 1), "ns", "set", "key2");
169  * ~~~~~~~~~~
170  *
171  * When the batch is no longer needed, then use as_batch_destroy() to
172  * release the batch and associated resources.
173  *
174  * @param batch The batch to initialize.
175  * @param size The number of keys to allocate.
176  *
177  * @relates as_batch
178  * @ingroup batch_object
179  */
180 as_batch * as_batch_init(as_batch * batch, uint32_t size);
181 
182 /**
183  * Destroy the batch of keys.
184  *
185  * ~~~~~~~~~~{.c}
186  * as_batch_destroy(batch);
187  * ~~~~~~~~~~
188  *
189  * @param batch The batch to release.
190  *
191  * @relates as_batch
192  * @ingroup batch_object
193  */
194 void as_batch_destroy(as_batch * batch);
195 
196 /**
197  * Get the key at given position of the batch. If the position is not
198  * within the allocated capacity for the batchm then NULL is returned.
199  *
200  * @param batch The batch to get the key from.
201  * @param i The position of the key.
202  *
203  * @return On success, the key at specified position. If position is invalid, then NULL.
204  *
205  * @relates as_batch
206  * @ingroup batch_object
207  */
208 static inline as_key * as_batch_keyat(const as_batch * batch, uint32_t i)
209 {
210  return (batch != NULL && batch->keys.entries != NULL && batch->keys.size > i) ? &batch->keys.entries[i] : NULL;
211 }
212 
213 #ifdef __cplusplus
214 } // end extern "C"
215 #endif