All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike_lmap.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 /**
24  * Functionality related to Large Map Data Type
25  */
26 
27 #pragma once
28 
29 #include <aerospike/aerospike.h>
30 #include <aerospike/as_error.h>
31 #include <aerospike/as_ldt.h>
32 #include <aerospike/as_list.h>
34 #include <aerospike/as_policy.h>
35 #include <aerospike/as_status.h>
36 #include <aerospike/as_key.h>
37 #include <aerospike/as_val.h>
38 #include <aerospike/as_boolean.h>
39 
40 /******************************************************************************
41  * FUNCTIONS
42  *****************************************************************************/
43 
44 /**
45  * Add a value into the lmap.
46  *
47  * ~~~~~~~~~~{.c}
48  * as_key key;
49  * as_key_init(&key, "myns", "myset", "mykey");
50  *
51  * as_ldt lmap;
52  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
53  *
54  * as_integer ival;
55  * as_integer_init(&ival, 123);
56  *
57  * if ( aerospike_lmap_put(&as, &err, NULL, &key, &lmap, (const as_val *) &ival, (as_val *) &ival) != AEROSPIKE_OK ) {
58  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
59  * }
60  * ~~~~~~~~~~
61  *
62  * @param as The aerospike instance to use for this operation.
63  * @param err The as_error to be populated if an error occurs.
64  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
65  * @param key The key of the record.
66  * @param ldt The ldt bin to insert values to.
67  * @param mkey The map-key.
68  * @param val The map-value associated with mkey.
69  *
70  * @return AEROSPIKE_OK if successful. Otherwise an error.
71  *
72  * @ingroup ldt_operations
73  */
75  aerospike * as, as_error * err, const as_policy_apply * policy,
76  const as_key * key, const as_ldt * ldt,
77  const as_val * mkey, const as_val * mval
78  );
79 
80 /**
81  * Add multiple entries into the lmap.
82  *
83  * ~~~~~~~~~~{.c}
84  * as_key key;
85  * as_key_init(&key, "myns", "myset", "mykey");
86  *
87  * as_ldt lmap;
88  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
89  *
90  *
91  * as_arraylist vals;
92  * as_arraylist_inita(&vals, 2);
93  * as_string s;
94  * as_string_init(s,"a string",false);
95  * as_arraylist_append_string(&vals, s);
96  * as_arraylist_append_int64(&vals, 35);
97  *
98  * if ( aerospike_lmap_put_all(&as, &err, NULL, &key, &lmap, (const as_map *)vals) != AEROSPIKE_OK ) {
99  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
100  * }
101  *
102  * ~~~~~~~~~~
103  *
104  * @param as The aerospike instance to use for this operation.
105  * @param err The as_error to be populated if an error occurs.
106  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
107  * @param key The key of the record.
108  * @param ldt The ldt bin to insert values to.
109  * @param vals A map containing the entries to add to the lmap.
110  *
111  * @return AEROSPIKE_OK if successful. Otherwise an error.
112  *
113  * @ingroup ldt_operations
114  */
116  aerospike * as, as_error * err, const as_policy_apply * policy,
117  const as_key * key, const as_ldt * ldt, const as_map * vals
118  );
119 
120 /**
121  * Get the value of an entry in the Lmap, using the given map-key
122  *
123  * ~~~~~~~~~~{.c}
124  * as_key key;
125  * as_key_init(&key, "myns", "myset", "mykey");
126  *
127  * as_ldt lmap;
128  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
129  *
130  * as_integer ival;
131  * as_integer_init(&ival, 123);
132  *
133  * boolean exists = false;
134  *
135  * if ( aerospike_lmap_get(&as, &err, NULL, &key, &lmap, &ikey, &p_val) != AEROSPIKE_OK ) {
136  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
137  * }
138  * else {
139  * // do logic because element exists
140  * }
141  * ~~~~~~~~~~
142  *
143  * @param as The aerospike instance to use for this operation.
144  * @param err The as_error to be populated if an error occurs.
145  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
146  * @param key The key of the record.
147  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
148  * @param exists Returned boolean value to indicate value exists.
149  *
150  * @return AEROSPIKE_OK if successful. Otherwise an error.
151  *
152  * @ingroup ldt_operations
153  */
154 
156  aerospike * as, as_error * err, const as_policy_apply * policy,
157  const as_key * key, const as_ldt * ldt, const as_val * mkey,
158  as_val ** mval
159  );
160 
161 /**
162  * Get all the entries in an lmap
163  *
164  * ~~~~~~~~~~{.c}
165  * as_key key;
166  * as_key_init(&key, "myns", "myset", "mykey");
167  *
168  * as_ldt lmap;
169  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
170  *
171  * as_map *p_map = NULL;
172  *
173  * if ( aerospike_lmap_get_all(&as, &err, NULL, &key, &lmap, &p_map) != AEROSPIKE_OK ) {
174  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
175  * }
176  * else {
177  * // do logic because element exists
178  * }
179  * ~~~~~~~~~~
180  *
181  * @param as The aerospike instance to use for this operation.
182  * @param err The as_error to be populated if an error occurs.
183  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
184  * @param key The key of the record.
185  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
186  * @param elements Returned pointer to the map of entries.
187  *
188  * @return AEROSPIKE_OK if successful. Otherwise an error.
189  *
190  * @ingroup ldt_operations
191  */
192 
194  aerospike * as, as_error * err, const as_policy_apply * policy,
195  const as_key * key, const as_ldt * ldt,
196  as_map ** elements
197  );
198 
199 /**
200  * Given an lmap bin, scan through all entries in the map, and apply the
201  * given filter function. If no filter function is specified, all values
202  * in the lmap will be returned.
203  *
204  * ~~~~~~~~~~{.c}
205  * as_key key;
206  * as_key_init(&key, "myns", "myset", "mykey");
207  *
208  * as_ldt lmap;
209  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
210  *
211  * as_map *p_map = NULL;
212  *
213  * if ( aerospike_lmap_filter(&as, &err, NULL, &key, &lmap,
214  * "counter_filter", NULL, (as_map *) &p_map) != AEROSPIKE_OK ) {
215  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
216  * }
217  * else {
218  * // process the returned elements
219  * as_map_destroy(p_map);
220  * }
221  * ~~~~~~~~~~
222  *
223  * @param as The aerospike instance to use for this operation.
224  * @param err The as_error to be populated if an error occurs.
225  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
226  * @param key The key of the record.
227  * @param ldt The lmap bin to operate on. If not an lmap bin, will return error.
228  * @param filter The name of the User-Defined-Function to use as a read-filter.
229  * The UDF should either return the entry, or nil, if filtered out.
230  * @param fargs The list of parameters passed in to the User-Defined-Function filter.
231  * @param elements The pointer to a map of entries returned from the function. Pointer should
232  * be NULL passed in.
233  *
234  * @return AEROSPIKE_OK if successful. Otherwise an error.
235  *
236  * @ingroup ldt_operations
237  */
239  aerospike * as, as_error * err, const as_policy_apply * policy,
240  const as_key * key, const as_ldt * ldt,
241  const as_udf_function_name filter, const as_list *filter_args,
242  as_map ** elements
243  );
244 
245 /**
246  * Look up a lmap and find how many elements it contains
247  *
248  * ~~~~~~~~~~{.c}
249  * as_key key;
250  * as_key_init(&key, "myns", "myset", "mykey");
251  *
252  * as_ldt lmap;
253  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
254  * uint32_t lmap_size = 0;
255  *
256  * if ( aerospike_lmap_size(&as, &err, NULL, &key, &lmap, &lmap_size) != AEROSPIKE_OK ) {
257  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
258  * }
259  * ~~~~~~~~~~
260  *
261  * @param as The aerospike instance to use for this operation.
262  * @param err The as_error to be populated if an error occurs.
263  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
264  * @param key The key of the record.
265  * @param ldt The lmap to operate on. If not an lmap bin, will return error.
266  * @param n Return the number of elements in the lmap.
267  *
268  * @return AEROSPIKE_OK if successful. Otherwise an error.
269  *
270  * @ingroup ldt_operations
271  */
273  aerospike * as, as_error * err, const as_policy_apply * policy,
274  const as_key * key, const as_ldt * ldt,
275  uint32_t *n
276  );
277 
278 /**
279  * Delete the given value from the lmap
280  *
281  * ~~~~~~~~~~{.c}
282  * as_key key;
283  * as_key_init(&key, "myns", "myset", "mykey");
284  *
285  * as_ldt lmap;
286  * as_ldt_init(&lmap, "lmap", AS_LDT_LMAP, NULL);
287  *
288  * as_integer ival;
289  * as_integer_init(&ival, 123);
290  *
291  * if ( aerospike_lmap_remove(&as, &err, NULL, &key, &lmap, (const as_val*)&ikey) != AEROSPIKE_OK ) {
292  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
293  * }
294  * ~~~~~~~~~~
295  *
296  * @param as The aerospike instance to use for this operation.
297  * @param err The as_error to be populated if an error occurs.
298  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
299  * @param key The key of the record.
300  * @param ldt The lmap bin to delete from. If not an lmap bin, will return error.
301  * @param val The value to delete from the set.
302  *
303  * @return AEROSPIKE_OK if successful. Otherwise an error.
304  *
305  * @ingroup ldt_operations
306  */
308  aerospike * as, as_error * err, const as_policy_apply * policy,
309  const as_key * key, const as_ldt * ldt, const as_val *mkey
310  );
311 
312 /**
313  * Destroy the lmap bin
314  *
315  * ~~~~~~~~~~{.c}
316  * as_key key;
317  * as_key_init(&key, "myns", "myset", "mykey");
318  *
319  * as_ldt lmap;
320  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
321  *
322  * if ( aerospike_lmap_destroy(&as, &err, NULL, &key, &lmap) != AEROSPIKE_OK ) {
323  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
324  * }
325  * ~~~~~~~~~~
326  *
327  * @param as The aerospike instance to use for this operation.
328  * @param err The as_error to be populated if an error occurs.
329  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
330  * @param key The key of the record.
331  * @param ldt The lmap bin to destroy. If not an lmap bin, will return error.
332  *
333  * @return AEROSPIKE_OK if successful. Otherwise an error.
334  *
335  * @ingroup ldt_operations
336  */
338  aerospike * as, as_error * err, const as_policy_apply * policy,
339  const as_key * key, const as_ldt * ldt
340  );
341