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-2017 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  do { \
129  if ( (__batch) != NULL ) {\
130  (__batch)->_free = false;\
131  (__batch)->keys.entries = (as_key*) alloca(sizeof(as_key) * (__size));\
132  if ( (__batch)->keys.entries ) { \
133  (__batch)->keys._free = false;\
134  (__batch)->keys.size = (__size);\
135  }\
136  } \
137  } while(0)
138 
139 /*********************************************************************************
140  * INSTANCE FUNCTIONS
141  *********************************************************************************/
142 
143 /**
144  * Create and initialize a heap allocated as_batch capable of storing
145  * `capacity` keys.
146  *
147  * ~~~~~~~~~~{.c}
148  * as_batch * batch = as_batch_new(2);
149  * as_key_init(as_batch_get(batch, 0), "ns", "set", "key1");
150  * as_key_init(as_batch_get(batch, 1), "ns", "set", "key2");
151  * ~~~~~~~~~~
152  *
153  * When the batch is no longer needed, then use as_batch_destroy() to
154  * release the batch and associated resources.
155  *
156  * @param size The number of keys to allocate.
157  *
158  * @relates as_batch
159  * @ingroup batch_object
160  */
161 as_batch * as_batch_new(uint32_t size);
162 
163 /**
164  * Initialize a stack allocated as_batch capable of storing `capacity` keys.
165  *
166  * ~~~~~~~~~~{.c}
167  * as_batch batch;
168  * as_batch_init(&batch, 2);
169  * as_key_init(as_batch_get(&batch, 0), "ns", "set", "key1");
170  * as_key_init(as_batch_get(&batch, 1), "ns", "set", "key2");
171  * ~~~~~~~~~~
172  *
173  * When the batch is no longer needed, then use as_batch_destroy() to
174  * release the batch and associated resources.
175  *
176  * @param batch The batch to initialize.
177  * @param size The number of keys to allocate.
178  *
179  * @relates as_batch
180  * @ingroup batch_object
181  */
182 as_batch * as_batch_init(as_batch * batch, uint32_t size);
183 
184 /**
185  * Destroy the batch of keys.
186  *
187  * ~~~~~~~~~~{.c}
188  * as_batch_destroy(batch);
189  * ~~~~~~~~~~
190  *
191  * @param batch The batch to release.
192  *
193  * @relates as_batch
194  * @ingroup batch_object
195  */
196 void as_batch_destroy(as_batch * batch);
197 
198 /**
199  * Get the key at given position of the batch. If the position is not
200  * within the allocated capacity for the batchm then NULL is returned.
201  *
202  * @param batch The batch to get the key from.
203  * @param i The position of the key.
204  *
205  * @return On success, the key at specified position. If position is invalid, then NULL.
206  *
207  * @relates as_batch
208  * @ingroup batch_object
209  */
210 static inline as_key * as_batch_keyat(const as_batch * batch, uint32_t i)
211 {
212  return (batch != NULL && batch->keys.entries != NULL && batch->keys.size > i) ? &batch->keys.entries[i] : NULL;
213 }
214 
215 #ifdef __cplusplus
216 } // end extern "C"
217 #endif
as_status
Definition: as_status.h:30
uint32_t size
Definition: as_batch.h:61
as_key * entries
Definition: as_batch.h:66
as_batch * as_batch_new(uint32_t size)
const as_key * key
Definition: as_batch.h:86
as_record record
Definition: as_batch.h:96
void as_batch_destroy(as_batch *batch)
bool _free
Definition: as_batch.h:45
as_batch * as_batch_init(as_batch *batch, uint32_t size)
as_status result
Definition: as_batch.h:91
Definition: as_key.h:199
static as_key * as_batch_keyat(const as_batch *batch, uint32_t i)
Definition: as_batch.h:210
struct as_batch::@0 keys