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