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