All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
aerospike_lmap.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 
19 /**
20  * Functionality related to Large Map Data Type
21  */
22 
23 #include <aerospike/aerospike.h>
24 #include <aerospike/as_error.h>
25 #include <aerospike/as_ldt.h>
26 #include <aerospike/as_list.h>
28 #include <aerospike/as_policy.h>
29 #include <aerospike/as_status.h>
30 #include <aerospike/as_key.h>
31 #include <aerospike/as_val.h>
32 #include <aerospike/as_boolean.h>
33 
34 /******************************************************************************
35  * FUNCTIONS
36  *****************************************************************************/
37 
38 /**
39  * Add a value into the lmap.
40  *
41  * ~~~~~~~~~~{.c}
42  * as_key key;
43  * as_key_init(&key, "myns", "myset", "mykey");
44  *
45  * as_ldt lmap;
46  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
47  *
48  * as_integer ival;
49  * as_integer_init(&ival, 123);
50  *
51  * if ( aerospike_lmap_put(&as, &err, NULL, &key, &lmap, (const as_val *) &ival, (as_val *) &ival) != AEROSPIKE_OK ) {
52  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
53  * }
54  * ~~~~~~~~~~
55  *
56  * @param as The aerospike instance to use for this operation.
57  * @param err The as_error to be populated if an error occurs.
58  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
59  * @param key The key of the record.
60  * @param ldt The ldt bin to insert values to.
61  * @param mkey The map-key.
62  * @param val The map-value associated with mkey.
63  *
64  * @return AEROSPIKE_OK if successful. Otherwise an error.
65  *
66  * @ingroup ldt_operations
67  */
69  aerospike * as, as_error * err, const as_policy_apply * policy,
70  const as_key * key, const as_ldt * ldt,
71  const as_val * mkey, const as_val * mval
72  );
73 
74 /**
75  * Add multiple entries into the lmap.
76  *
77  * ~~~~~~~~~~{.c}
78  * as_key key;
79  * as_key_init(&key, "myns", "myset", "mykey");
80  *
81  * as_ldt lmap;
82  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
83  *
84  *
85  * as_arraylist vals;
86  * as_arraylist_inita(&vals, 2);
87  * as_string s;
88  * as_string_init(s,"a string",false);
89  * as_arraylist_append_string(&vals, s);
90  * as_arraylist_append_int64(&vals, 35);
91  *
92  * if ( aerospike_lmap_put_all(&as, &err, NULL, &key, &lmap, (const as_map *)vals) != AEROSPIKE_OK ) {
93  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
94  * }
95  *
96  * ~~~~~~~~~~
97  *
98  * @param as The aerospike instance to use for this operation.
99  * @param err The as_error to be populated if an error occurs.
100  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
101  * @param key The key of the record.
102  * @param ldt The ldt bin to insert values to.
103  * @param vals A map containing the entries to add to the lmap.
104  *
105  * @return AEROSPIKE_OK if successful. Otherwise an error.
106  *
107  * @ingroup ldt_operations
108  */
110  aerospike * as, as_error * err, const as_policy_apply * policy,
111  const as_key * key, const as_ldt * ldt, const as_map * vals
112  );
113 
114 /**
115  * Get the value of an entry in the Lmap, using the given map-key
116  *
117  * ~~~~~~~~~~{.c}
118  * as_key key;
119  * as_key_init(&key, "myns", "myset", "mykey");
120  *
121  * as_ldt lmap;
122  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
123  *
124  * as_integer ival;
125  * as_integer_init(&ival, 123);
126  *
127  * boolean exists = false;
128  *
129  * if ( aerospike_lmap_get(&as, &err, NULL, &key, &lmap, &ikey, &p_val) != AEROSPIKE_OK ) {
130  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
131  * }
132  * else {
133  * // do logic because element exists
134  * }
135  * ~~~~~~~~~~
136  *
137  * @param as The aerospike instance to use for this operation.
138  * @param err The as_error to be populated if an error occurs.
139  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
140  * @param key The key of the record.
141  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
142  * @param exists Returned boolean value to indicate value exists.
143  *
144  * @return AEROSPIKE_OK if successful. Otherwise an error.
145  *
146  * @ingroup ldt_operations
147  */
148 
150  aerospike * as, as_error * err, const as_policy_apply * policy,
151  const as_key * key, const as_ldt * ldt, const as_val * mkey,
152  as_val ** mval
153  );
154 
155 /**
156  * Get all the entries in an lmap
157  *
158  * ~~~~~~~~~~{.c}
159  * as_key key;
160  * as_key_init(&key, "myns", "myset", "mykey");
161  *
162  * as_ldt lmap;
163  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
164  *
165  * as_map *p_map = NULL;
166  *
167  * if ( aerospike_lmap_get_all(&as, &err, NULL, &key, &lmap, &p_map) != AEROSPIKE_OK ) {
168  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
169  * }
170  * else {
171  * // do logic because element exists
172  * }
173  * ~~~~~~~~~~
174  *
175  * @param as The aerospike instance to use for this operation.
176  * @param err The as_error to be populated if an error occurs.
177  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
178  * @param key The key of the record.
179  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
180  * @param elements Returned pointer to the map of entries.
181  *
182  * @return AEROSPIKE_OK if successful. Otherwise an error.
183  *
184  * @ingroup ldt_operations
185  */
186 
188  aerospike * as, as_error * err, const as_policy_apply * policy,
189  const as_key * key, const as_ldt * ldt,
190  as_map ** elements
191  );
192 
193 /**
194  * Given an lmap bin, scan through all entries in the map, and apply the
195  * given filter function. If no filter function is specified, all values
196  * in the lmap will be returned.
197  *
198  * ~~~~~~~~~~{.c}
199  * as_key key;
200  * as_key_init(&key, "myns", "myset", "mykey");
201  *
202  * as_ldt lmap;
203  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
204  *
205  * as_map *p_map = NULL;
206  *
207  * if ( aerospike_lmap_filter(&as, &err, NULL, &key, &lmap,
208  * "counter_filter", NULL, (as_map *) &p_map) != AEROSPIKE_OK ) {
209  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
210  * }
211  * else {
212  * // process the returned elements
213  * as_map_destroy(p_map);
214  * }
215  * ~~~~~~~~~~
216  *
217  * @param as The aerospike instance to use for this operation.
218  * @param err The as_error to be populated if an error occurs.
219  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
220  * @param key The key of the record.
221  * @param ldt The lmap bin to operate on. If not an lmap bin, will return error.
222  * @param filter The name of the User-Defined-Function to use as a read-filter.
223  * The UDF should either return the entry, or nil, if filtered out.
224  * @param fargs The list of parameters passed in to the User-Defined-Function filter.
225  * @param elements The pointer to a map of entries returned from the function. Pointer should
226  * be NULL passed in.
227  *
228  * @return AEROSPIKE_OK if successful. Otherwise an error.
229  *
230  * @ingroup ldt_operations
231  */
233  aerospike * as, as_error * err, const as_policy_apply * policy,
234  const as_key * key, const as_ldt * ldt,
235  const as_udf_function_name filter, const as_list *filter_args,
236  as_map ** elements
237  );
238 
239 /**
240  * Look up a lmap and find how many elements it contains
241  *
242  * ~~~~~~~~~~{.c}
243  * as_key key;
244  * as_key_init(&key, "myns", "myset", "mykey");
245  *
246  * as_ldt lmap;
247  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
248  * uint32_t lmap_size = 0;
249  *
250  * if ( aerospike_lmap_size(&as, &err, NULL, &key, &lmap, &lmap_size) != AEROSPIKE_OK ) {
251  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
252  * }
253  * ~~~~~~~~~~
254  *
255  * @param as The aerospike instance to use for this operation.
256  * @param err The as_error to be populated if an error occurs.
257  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
258  * @param key The key of the record.
259  * @param ldt The lmap to operate on. If not an lmap bin, will return error.
260  * @param n Return the number of elements in the lmap.
261  *
262  * @return AEROSPIKE_OK if successful. Otherwise an error.
263  *
264  * @ingroup ldt_operations
265  */
267  aerospike * as, as_error * err, const as_policy_apply * policy,
268  const as_key * key, const as_ldt * ldt,
269  uint32_t *n
270  );
271 
272 /**
273  * Delete the given value from the lmap
274  *
275  * ~~~~~~~~~~{.c}
276  * as_key key;
277  * as_key_init(&key, "myns", "myset", "mykey");
278  *
279  * as_ldt lmap;
280  * as_ldt_init(&lmap, "lmap", AS_LDT_LMAP, NULL);
281  *
282  * as_integer ival;
283  * as_integer_init(&ival, 123);
284  *
285  * if ( aerospike_lmap_remove(&as, &err, NULL, &key, &lmap, (const as_val*)&ikey) != AEROSPIKE_OK ) {
286  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
287  * }
288  * ~~~~~~~~~~
289  *
290  * @param as The aerospike instance to use for this operation.
291  * @param err The as_error to be populated if an error occurs.
292  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
293  * @param key The key of the record.
294  * @param ldt The lmap bin to delete from. If not an lmap bin, will return error.
295  * @param val The value to delete from the set.
296  *
297  * @return AEROSPIKE_OK if successful. Otherwise an error.
298  *
299  * @ingroup ldt_operations
300  */
302  aerospike * as, as_error * err, const as_policy_apply * policy,
303  const as_key * key, const as_ldt * ldt, const as_val *mkey
304  );
305 
306 /**
307  * Destroy the lmap bin
308  *
309  * ~~~~~~~~~~{.c}
310  * as_key key;
311  * as_key_init(&key, "myns", "myset", "mykey");
312  *
313  * as_ldt lmap;
314  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
315  *
316  * if ( aerospike_lmap_destroy(&as, &err, NULL, &key, &lmap) != AEROSPIKE_OK ) {
317  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
318  * }
319  * ~~~~~~~~~~
320  *
321  * @param as The aerospike instance to use for this operation.
322  * @param err The as_error to be populated if an error occurs.
323  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
324  * @param key The key of the record.
325  * @param ldt The lmap bin to destroy. If not an lmap bin, will return error.
326  *
327  * @return AEROSPIKE_OK if successful. Otherwise an error.
328  *
329  * @ingroup ldt_operations
330  */
332  aerospike * as, as_error * err, const as_policy_apply * policy,
333  const as_key * key, const as_ldt * ldt
334  );
335 
336 /**
337  * Change an LDT storage capacity (in number of elements)
338  *
339  * ~~~~~~~~~~{.c}
340  * as_key key;
341  * as_key_init(&key, "myns", "myset", "mykey");
342  *
343  * as_ldt lmap;
344  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
345  * uint32_t ldt_capacity = 0;
346  *
347  * if ( aerospike_lmap_set_capacity(&as, &err, NULL, &key, &lmap, ldt_capacity) != AEROSPIKE_OK ) {
348  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
349  * }
350  * ~~~~~~~~~~
351  *
352  * @param as The aerospike instance to use for this operation.
353  * @param err The as_error to be populated if an error occurs.
354  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
355  * @param key The key of the record.
356  * @param ldt The LDT to check
357  * @param ldt_capacity The new capacity for this LDT, in terms of elements, not bytes
358  *
359  * @return AEROSPIKE_OK if successful. Otherwise an error.
360  *
361  * @ingroup ldt_operations
362  */
364  aerospike * as, as_error * err, const as_policy_apply * policy,
365  const as_key * key, const as_ldt * ldt, uint32_t ldt_capacity
366  );
367 
368 /**
369  * Get an LDTs storage capacity (in number of elements)
370  *
371  * ~~~~~~~~~~{.c}
372  * as_key key;
373  * as_key_init(&key, "myns", "myset", "mykey");
374  *
375  * as_ldt lmap;
376  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
377  * uint32_t ldt_capacity = 0;
378  *
379  * if ( aerospike_lmap_get_capacity(&as, &err, NULL, &key, &lmap, &ldt_capacity) != AEROSPIKE_OK ) {
380  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
381  * }
382  * ~~~~~~~~~~
383  *
384  * @param as The aerospike instance to use for this operation.
385  * @param err The as_error to be populated if an error occurs.
386  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
387  * @param key The key of the record.
388  * @param ldt The LDT bin to operate on
389  * @param ldt_capacity The LDT Capacity, in terms of elements, not bytes.
390  *
391  * @return AEROSPIKE_OK if successful. Otherwise an error.
392  *
393  * @ingroup ldt_operations
394  */
396  aerospike * as, as_error * err, const as_policy_apply * policy,
397  const as_key * key, const as_ldt * ldt,
398  uint32_t *ldt_capacity
399  );
400 
401 /**
402  * Check to see if an LDT object exists in this record bin.
403  *
404  * ~~~~~~~~~~{.c}
405  * as_key key;
406  * as_key_init(&key, "myns", "myset", "mykey");
407  *
408  * as_ldt lmap;
409  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
410  * uint32_t ldt_exists = 0;
411  *
412  * if ( aerospike_lmap_ldt_exists(&as, &err, NULL, &key, &lmap, &ldt_exists) != AEROSPIKE_OK ) {
413  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
414  * }
415  * ~~~~~~~~~~
416  *
417  * @param as The aerospike instance to use for this operation.
418  * @param err The as_error to be populated if an error occurs.
419  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
420  * @param key The key of the record.
421  * @param ldt The LDT to operate on. If not an LMAP bin, will return error.
422  * @param ldt_exists Ptr to as_boolean: Set to TRUE if ldt exists, otherwise false.
423  *
424  * @return AEROSPIKE_OK if successful. Otherwise an error.
425  *
426  * @ingroup ldt_operations
427  */
429  aerospike * as, as_error * err, const as_policy_apply * policy,
430  const as_key * key, const as_ldt * ldt,
431  as_boolean *ldt_exists
432  );
433 
434 
as_status aerospike_lmap_get(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *mkey, as_val **mval)
as_status aerospike_lmap_filter(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_udf_function_name filter, const as_list *filter_args, as_map **elements)
Definition: as_map.h:57
as_status
Definition: as_status.h:26
as_status aerospike_lmap_get_all(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, as_map **elements)
as_status aerospike_lmap_put(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *mkey, const as_val *mval)
Definition: as_val.h:51
char as_udf_function_name[AS_UDF_FUNCTION_MAX_SIZE]
Definition: as_udf.h:78
as_status aerospike_lmap_put_all(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_map *vals)
as_status aerospike_lmap_get_capacity(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t *ldt_capacity)
as_status aerospike_lmap_set_capacity(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t ldt_capacity)
as_status aerospike_lmap_destroy(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt)
as_status aerospike_lmap_ldt_exists(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, as_boolean *ldt_exists)
Definition: as_ldt.h:48
as_status aerospike_lmap_remove(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *mkey)
Definition: as_key.h:193
as_status aerospike_lmap_size(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t *n)