All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_scan.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 #pragma GCC diagnostic ignored "-Waddress"
19 
20 #include <aerospike/as_bin.h>
21 #include <aerospike/as_key.h>
22 #include <aerospike/as_udf.h>
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /******************************************************************************
29  * MACROS
30  *****************************************************************************/
31 
32 /**
33  * Default value for as_scan.priority
34  */
35 #define AS_SCAN_PRIORITY_DEFAULT AS_SCAN_PRIORITY_AUTO
36 
37 /**
38  * Default value for as_scan.percent
39  */
40 #define AS_SCAN_PERCENT_DEFAULT 100
41 
42 /**
43  * Default value for as_scan.no_bins
44  */
45 #define AS_SCAN_NOBINS_DEFAULT false
46 
47 /**
48  * Default value for as_scan.concurrent
49  */
50 #define AS_SCAN_CONCURRENT_DEFAULT false
51 
52 /**
53  * Default value for as_scan.deserialize_list_map
54  */
55 #define AS_SCAN_DESERIALIZE_DEFAULT true
56 
57 /******************************************************************************
58  * TYPES
59  *****************************************************************************/
60 
61 /**
62  * Priority levels for a scan operation.
63  */
64 typedef enum as_scan_priority_e {
65 
66  /**
67  * The cluster will auto adjust the scan priority.
68  */
70 
71  /**
72  * Low priority scan.
73  */
75 
76  /**
77  * Medium priority scan.
78  */
80 
81  /**
82  * High priority scan.
83  */
85 
87 
88 /**
89  * The status of a particular background scan.
90  */
91 typedef enum as_scan_status_e {
92 
93  /**
94  * The scan status is undefined.
95  * This is likely due to the status not being properly checked.
96  */
98 
99  /**
100  * The scan is currently running.
101  */
103 
104  /**
105  * The scan was aborted. Due to failure or the user.
106  */
108 
109  /**
110  * The scan completed successfully.
111  */
113 
115 
116 /**
117  * Information about a particular background scan.
118  *
119  * @ingroup as_scan_object
120  */
121 typedef struct as_scan_info_s {
122 
123  /**
124  * Status of the scan.
125  */
127 
128  /**
129  * Progress estimate for the scan, as percentage.
130  */
131  uint32_t progress_pct;
132 
133  /**
134  * How many records have been scanned.
135  */
136  uint32_t records_scanned;
137 
138 } as_scan_info;
139 
140 /**
141  * Sequence of bins which should be selected during a scan.
142  *
143  * Entries can either be initialized on the stack or on the heap.
144  *
145  * Initialization should be performed via a query object, using:
146  * - as_scan_select_init()
147  * - as_scan_select_inita()
148  */
149 typedef struct as_scan_bins_s {
150 
151  /**
152  * @private
153  * If true, then as_scan_destroy() will free this instance.
154  */
155  bool _free;
156 
157  /**
158  * Number of entries allocated
159  */
160  uint16_t capacity;
161 
162  /**
163  * Number of entries used
164  */
165  uint16_t size;
166 
167  /**
168  * Sequence of entries
169  */
171 
172 } as_scan_bins;
173 
174 /**
175  * In order to execute a scan using the Scan API, an as_scan object
176  * must be initialized and populated.
177  *
178  * ## Initialization
179  *
180  * Before using an as_scan, it must be initialized via either:
181  * - as_scan_init()
182  * - as_scan_new()
183  *
184  * as_scan_init() should be used on a stack allocated as_scan. It will
185  * initialize the as_scan with the given namespace and set. On success,
186  * it will return a pointer to the initialized as_scan. Otherwise, NULL
187  * is returned.
188  *
189  * ~~~~~~~~~~{.c}
190  * as_scan scan;
191  * as_scan_init(&scan, "namespace", "set");
192  * ~~~~~~~~~~
193  *
194  * as_scan_new() should be used to allocate and initialize a heap allocated
195  * as_scan. It will allocate the as_scan, then initialized it with the
196  * given namespace and set. On success, it will return a pointer to the
197  * initialized as_scan. Otherwise, NULL is returned.
198  *
199  * ~~~~~~~~~~{.c}
200  * as_scan * scan = as_scan_new("namespace", "set");
201  * ~~~~~~~~~~
202  *
203  * ## Destruction
204  *
205  * When you are finished with the as_scan, you can destroy it and associated
206  * resources:
207  *
208  * ~~~~~~~~~~{.c}
209  * as_scan_destroy(scan);
210  * ~~~~~~~~~~
211  *
212  * ## Usage
213  *
214  * An initialized as_query can be populated with additional fields.
215  *
216  * ### Selecting Bins
217  *
218  * as_scan_select() is used to specify the bins to be selected by the scan.
219  * If a scan specifies bins to be selected, then only those bins will be
220  * returned. If no bins are selected, then all bins will be returned.
221  *
222  * ~~~~~~~~~~{.c}
223  * as_scan_select(query, "bin1");
224  * as_scan_select(query, "bin2");
225  * ~~~~~~~~~~
226  *
227  * Before adding bins to select, the select structure must be initialized via
228  * either:
229  * - as_scan_select_inita() - Initializes the structure on the stack.
230  * - as_scan_select_init() - Initializes the structure on the heap.
231  *
232  * Both functions are given the number of bins to be selected.
233  *
234  * A complete example using as_scan_select_inita()
235  *
236  * ~~~~~~~~~~{.c}
237  * as_scan_select_inita(query, 2);
238  * as_scan_select(query, "bin1");
239  * as_scan_select(query, "bin2");
240  * ~~~~~~~~~~
241  *
242  * ### Returning only meta data
243  *
244  * A scan can return only record meta data, and exclude bins.
245  *
246  * ~~~~~~~~~~{.c}
247  * as_scan_set_nobins(scan, true);
248  * ~~~~~~~~~~
249  *
250  * ### Scan nodes in parallel
251  *
252  * A scan can be made to scan all the nodes in parallel
253  *
254  * ~~~~~~~~~~{.c}
255  * as_scan_set_concurrent(scan, true);
256  * ~~~~~~~~~~
257  *
258  * ### Scan a Percentage of Records
259  *
260  * A scan can define the percentage of record in the cluster to be scaned.
261  *
262  * ~~~~~~~~~~{.c}
263  * as_scan_set_percent(scan, 100);
264  * ~~~~~~~~~~
265  *
266  * ### Scan a Priority
267  *
268  * To set the priority of the scan, the set as_scan.priority.
269  *
270  * The priority of a scan can be defined as either:
271  * - `AS_SCAN_PRIORITY_AUTO`
272  * - `AS_SCAN_PRIORITY_LOW`
273  * - `AS_SCAN_PRIORITY_MEDIUM`
274  * - `AS_SCAN_PRIORITY_HIGH`
275  *
276  * ~~~~~~~~~~{.c}
277  * as_scan_set_priority(scan, AS_SCAN_PRIORITY_LOW);
278  * ~~~~~~~~~~
279  *
280  * ### Applying a UDF to each Record Scanned
281  *
282  * A UDF can be applied to each record scanned.
283  *
284  * To define the UDF for the scan, use as_scan_apply_each().
285  *
286  * ~~~~~~~~~~{.c}
287  * as_scan_apply_each(scan, "udf_module", "udf_function", arglist);
288  * ~~~~~~~~~~
289  *
290  * @ingroup client_objects
291  */
292 typedef struct as_scan_s {
293 
294  /**
295  * @private
296  * If true, then as_scan_destroy() will free this instance.
297  */
298  bool _free;
299 
300  /**
301  * Priority of scan.
302  *
303  * Default value is AS_SCAN_PRIORITY_DEFAULT.
304  */
306 
307  /**
308  * Percentage of the data to scan.
309  *
310  * Default value is AS_SCAN_PERCENT_DEFAULT.
311  */
312  uint8_t percent;
313 
314  /**
315  * Set to true if the scan should return only the metadata of the record.
316  *
317  * Default value is AS_SCAN_NOBINS_DEFAULT.
318  */
319  bool no_bins;
320 
321  /**
322  * Set to true if the scan should scan all the nodes in parallel
323  *
324  * Default value is AS_SCAN_CONCURRENT_DEFAULT.
325  */
327 
328  /**
329  * Set to true if the scan should deserialize list and map raw bytes.
330  * Set to false for backup programs that just need access to raw bytes.
331  *
332  * Default value is AS_SCAN_DESERIALIZE_DEFAULT.
333  */
335 
336  /**
337  * @memberof as_scan
338  * Namespace to be scanned.
339  *
340  * Should be initialized via either:
341  * - as_scan_init() - To initialize a stack allocated scan.
342  * - as_scan_new() - To heap allocate and initialize a scan.
343  *
344  */
346 
347  /**
348  * Set to be scanned.
349  *
350  * Should be initialized via either:
351  * - as_scan_init() - To initialize a stack allocated scan.
352  * - as_scan_new() - To heap allocate and initialize a scan.
353  *
354  */
356 
357  /**
358  * Name of bins to select.
359  *
360  * Use either of the following function to initialize:
361  * - as_scan_select_init() - To initialize on the heap.
362  * - as_scan_select_inita() - To initialize on the stack.
363  *
364  * Use as_scan_select() to populate.
365  */
367 
368  /**
369  * Apply the UDF for each record scanned on the server.
370  *
371  * Should be set via `as_scan_apply_each()`.
372  */
374 
375 } as_scan;
376 
377 /******************************************************************************
378  * INSTANCE FUNCTIONS
379  *****************************************************************************/
380 
381 /**
382  * Initializes a scan.
383  *
384  * ~~~~~~~~~~{.c}
385  * as_scan scan;
386  * as_scan_init(&scan, "test", "demo");
387  * ~~~~~~~~~~
388  *
389  * When you no longer require the scan, you should release the scan and
390  * related resources via `as_scan_destroy()`.
391  *
392  * @param scan The scan to initialize.
393  * @param ns The namespace to scan.
394  * @param set The set to scan.
395  *
396  * @returns On succes, the initialized scan. Otherwise NULL.
397  *
398  * @relates as_scan
399  * @ingroup as_scan_object
400  */
401 as_scan * as_scan_init(as_scan * scan, const as_namespace ns, const as_set set);
402 
403 /**
404  * Create and initializes a new scan on the heap.
405  *
406  * ~~~~~~~~~~{.c}
407  * as_scan * scan = as_scan_new("test","demo");
408  * ~~~~~~~~~~
409  *
410  * When you no longer require the scan, you should release the scan and
411  * related resources via `as_scan_destroy()`.
412  *
413  * @param ns The namespace to scan.
414  * @param set The set to scan.
415  *
416  * @returns On success, a new scan. Otherwise NULL.
417  *
418  * @relates as_scan
419  * @ingroup as_scan_object
420  */
421 as_scan * as_scan_new(const as_namespace ns, const as_set set);
422 
423 /**
424  * Releases all resources allocated to the scan.
425  *
426  * ~~~~~~~~~~{.c}
427  * as_scan_destroy(scan);
428  * ~~~~~~~~~~
429  *
430  * @relates as_scan
431  * @ingroup as_scan_object
432  */
433 void as_scan_destroy(as_scan * scan);
434 
435 /******************************************************************************
436  * SELECT FUNCTIONS
437  *****************************************************************************/
438 
439 /**
440  * Initializes `as_scan.select` with a capacity of `n` using `alloca`
441  *
442  * For heap allocation, use `as_scan_select_init()`.
443  *
444  * ~~~~~~~~~~{.c}
445  * as_scan_select_inita(&scan, 2);
446  * as_scan_select(&scan, "bin1");
447  * as_scan_select(&scan, "bin2");
448  * ~~~~~~~~~~
449  *
450  * @param __scan The scan to initialize.
451  * @param __n The number of bins to allocate.
452  *
453  * @ingroup as_scan_object
454  */
455 #define as_scan_select_inita(__scan, __n) \
456  if ( (__scan) != NULL && (__scan)->select.entries == NULL ) {\
457  (__scan)->select.entries = (as_bin_name *) alloca(__n * sizeof(as_bin_name));\
458  if ( (__scan)->select.entries ) { \
459  (__scan)->select._free = false;\
460  (__scan)->select.capacity = __n;\
461  (__scan)->select.size = 0;\
462  }\
463  }
464 
465 /**
466  * Initializes `as_scan.select` with a capacity of `n` using `malloc()`.
467  *
468  * For stack allocation, use `as_scan_select_inita()`.
469  *
470  * ~~~~~~~~~~{.c}
471  * as_scan_select_init(&scan, 2);
472  * as_scan_select(&scan, "bin1");
473  * as_scan_select(&scan, "bin2");
474  * ~~~~~~~~~~
475  *
476  * @param scan The scan to initialize.
477  * @param n The number of bins to allocate.
478  *
479  * @return On success, the initialized. Otherwise an error occurred.
480  *
481  * @relates as_scan
482  * @ingroup as_scan_object
483  */
484 bool as_scan_select_init(as_scan * scan, uint16_t n);
485 
486 /**
487  * Select bins to be projected from matching records.
488  *
489  * You have to ensure as_scan.select has sufficient capacity, prior to
490  * adding a bin. If capacity is insufficient then false is returned.
491  *
492  * ~~~~~~~~~~{.c}
493  * as_scan_select_init(&scan, 2);
494  * as_scan_select(&scan, "bin1");
495  * as_scan_select(&scan, "bin2");
496  * ~~~~~~~~~~
497  *
498  * @param scan The scan to modify.
499  * @param bin The name of the bin to select.
500  *
501  * @return On success, true. Otherwise an error occurred.
502  *
503  * @relates as_scan
504  * @ingroup as_scan_object
505  */
506 bool as_scan_select(as_scan * scan, const char * bin);
507 
508 /******************************************************************************
509  * MODIFIER FUNCTIONS
510  *****************************************************************************/
511 
512 /**
513  * The percentage of data to scan.
514  *
515  * ~~~~~~~~~~{.c}
516  * as_scan_set_percent(&q, 100);
517  * ~~~~~~~~~~
518  *
519  * @param scan The scan to set the priority on.
520  * @param percent The percent to scan.
521  *
522  * @return On success, true. Otherwise an error occurred.
523  *
524  * @relates as_scan
525  * @ingroup as_scan_object
526  */
527 bool as_scan_set_percent(as_scan * scan, uint8_t percent);
528 
529 /**
530  * Set the priority for the scan.
531  *
532  * ~~~~~~~~~~{.c}
533  * as_scan_set_priority(&q, AS_SCAN_PRIORITY_LOW);
534  * ~~~~~~~~~~
535  *
536  * @param scan The scan to set the priority on.
537  * @param priority The priority for the scan.
538  *
539  * @return On success, true. Otherwise an error occurred.
540  *
541  * @relates as_scan
542  * @ingroup as_scan_object
543  */
544 bool as_scan_set_priority(as_scan * scan, as_scan_priority priority);
545 
546 /**
547  * Do not return bins. This will only return the metadata for the records.
548  *
549  * ~~~~~~~~~~{.c}
550  * as_scan_set_nobins(&q, true);
551  * ~~~~~~~~~~
552  *
553  * @param scan The scan to set the priority on.
554  * @param nobins If true, then do not return bins.
555  *
556  * @return On success, true. Otherwise an error occurred.
557  *
558  * @relates as_scan
559  * @ingroup as_scan_object
560  */
561 bool as_scan_set_nobins(as_scan * scan, bool nobins);
562 
563 /**
564  * Scan all the nodes in prallel
565  *
566  * ~~~~~~~~~~{.c}
567  * as_scan_set_concurrent(&q, true);
568  * ~~~~~~~~~~
569  *
570  * @param scan The scan to set the concurrency on.
571  * @param concurrent If true, scan all the nodes in parallel
572  *
573  * @return On success, true. Otherwise an error occurred.
574  */
575 bool as_scan_set_concurrent(as_scan * scan, bool concurrent);
576 
577 /**
578  * Apply a UDF to each record scanned on the server.
579  *
580  * ~~~~~~~~~~{.c}
581  * as_arraylist arglist;
582  * as_arraylist_init(&arglist, 2, 0);
583  * as_arraylist_append_int64(&arglist, 1);
584  * as_arraylist_append_int64(&arglist, 2);
585  *
586  * as_scan_apply_each(&q, "module", "func", (as_list *) &arglist);
587  *
588  * as_arraylist_destroy(&arglist);
589  * ~~~~~~~~~~
590  *
591  * @param scan The scan to apply the UDF to.
592  * @param module The module containing the function to execute.
593  * @param function The function to execute.
594  * @param arglist The arguments for the function.
595  *
596  * @return On success, true. Otherwise an error occurred.
597  *
598  * @relates as_scan
599  * @ingroup as_scan_object
600  */
601 bool as_scan_apply_each(as_scan * scan, const char * module, const char * function, as_list * arglist);
602 
603 #ifdef __cplusplus
604 } // end extern "C"
605 #endif
uint8_t percent
Definition: as_scan.h:312
as_namespace ns
Definition: as_scan.h:345
bool as_scan_select(as_scan *scan, const char *bin)
as_scan * as_scan_init(as_scan *scan, const as_namespace ns, const as_set set)
as_udf_call apply_each
Definition: as_scan.h:373
uint32_t records_scanned
Definition: as_scan.h:136
char as_namespace[AS_NAMESPACE_MAX_SIZE]
Definition: as_key.h:66
bool _free
Definition: as_scan.h:155
as_scan_status status
Definition: as_scan.h:126
as_set set
Definition: as_scan.h:355
bool as_scan_select_init(as_scan *scan, uint16_t n)
uint16_t capacity
Definition: as_scan.h:160
bool as_scan_set_percent(as_scan *scan, uint8_t percent)
uint16_t size
Definition: as_scan.h:165
void as_scan_destroy(as_scan *scan)
uint32_t progress_pct
Definition: as_scan.h:131
as_scan_priority priority
Definition: as_scan.h:305
as_scan * as_scan_new(const as_namespace ns, const as_set set)
bool deserialize_list_map
Definition: as_scan.h:334
bool no_bins
Definition: as_scan.h:319
bool as_scan_set_concurrent(as_scan *scan, bool concurrent)
bool as_scan_apply_each(as_scan *scan, const char *module, const char *function, as_list *arglist)
bool as_scan_set_nobins(as_scan *scan, bool nobins)
char as_bin_name[AS_BIN_NAME_MAX_SIZE]
Definition: as_bin.h:52
as_bin_name * entries
Definition: as_scan.h:170
bool as_scan_set_priority(as_scan *scan, as_scan_priority priority)
bool _free
Definition: as_scan.h:298
as_scan_bins select
Definition: as_scan.h:366
as_scan_priority
Definition: as_scan.h:64
bool concurrent
Definition: as_scan.h:326
as_scan_status
Definition: as_scan.h:91
char as_set[AS_SET_MAX_SIZE]
Definition: as_key.h:73