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