All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_policy.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  * @defgroup client_policies Client Policies
25  *
26  * Policies define the behavior of database operations.
27  *
28  * Policies fall into two groups: policy values and operation policies.
29  * A policy value is a single value which defines how the client behaves. An
30  * operation policy is a group of policy values which affect an operation.
31  *
32  * ## Policy Values
33  *
34  * The following are the policy values. For details, please see the documentation
35  * for each policy value
36  *
37  * - as_policy_key
38  * - as_policy_gen
39  * - as_policy_retry
40  * - as_policy_exists
41  *
42  * ## Operation Policies
43  *
44  * The following are the operation policies. Operation policies are groups of
45  * policy values for a type of operation.
46  *
47  * - as_policy_batch
48  * - as_policy_info
49  * - as_policy_operate
50  * - as_policy_read
51  * - as_policy_remove
52  * - as_policy_query
53  * - as_policy_scan
54  * - as_policy_write
55  *
56  */
57 
58 #pragma once
59 
60 #include <stdbool.h>
61 #include <stdint.h>
62 
63 /******************************************************************************
64  * MACROS
65  *****************************************************************************/
66 
67 /**
68  * Default timeout value
69  *
70  * @ingroup client_policies
71  */
72 #define AS_POLICY_TIMEOUT_DEFAULT 1000
73 
74 /**
75  * Default as_policy_retry value
76  *
77  * @ingroup client_policies
78  */
79 #define AS_POLICY_RETRY_DEFAULT AS_POLICY_RETRY_NONE
80 
81 /**
82  * Default as_policy_gen value
83  *
84  * @ingroup client_policies
85  */
86 #define AS_POLICY_GEN_DEFAULT AS_POLICY_GEN_IGNORE
87 
88 /**
89  * Default as_policy_key value
90  *
91  * @ingroup client_policies
92  */
93 #define AS_POLICY_KEY_DEFAULT AS_POLICY_KEY_DIGEST
94 
95 /**
96  * Default as_policy_exists value
97  *
98  * @ingroup client_policies
99  */
100 #define AS_POLICY_EXISTS_DEFAULT AS_POLICY_EXISTS_IGNORE
101 
102 /******************************************************************************
103  * TYPES
104  *****************************************************************************/
105 
106 /**
107  * Retry Policy
108  *
109  * Specifies the behavior of failed operations.
110  *
111  * @ingroup client_policies
112  */
113 typedef enum as_policy_retry_e {
114 
115  /**
116  * The policy is undefined.
117  *
118  * If set, then the value will default to
119  * either as_config.policies.retry
120  * or `AS_POLICY_RETRY_DEFAULT`.
121  */
123 
124  /**
125  * Only attempt an operation once.
126  */
128 
129  /**
130  * If an operation fails, attempt the operation
131  * one more time.
132  */
134 
136 
137 /**
138  * Generation Policy
139  *
140  * Specifies the behavior of record modifications with regard to the
141  * generation value.
142  *
143  * @ingroup client_policies
144  */
145 typedef enum as_policy_gen_e {
146 
147  /**
148  * The policy is undefined.
149  *
150  * If set, then the value will default to
151  * either as_config.policies.gen
152  * or `AS_POLICY_GEN_DEFAULT`.
153  */
155 
156  /**
157  * Write a record, regardless of generation.
158  */
160 
161  /**
162  * Write a record, ONLY if generations are equal
163  */
165 
166  /**
167  * Write a record, ONLY if local generation is
168  * greater-than remote generation
169  */
171 
172  /**
173  * Write a record creating a duplicate, ONLY if
174  * the generation collides (?)
175  */
177 
178 } as_policy_gen;
179 
180 /**
181  * Key Policy
182  *
183  * Specifies the behavior for whether keys or digests
184  * should be sent to the cluster.
185  *
186  * @ingroup client_policies
187  */
188 typedef enum as_policy_key_e {
189 
190  /**
191  * The policy is undefined.
192  *
193  * If set, then the value will default to either as_config.policies.key
194  * or `AS_POLICY_KEY_DEFAULT`.
195  */
197 
198  /**
199  * Send the digest value of the key.
200  *
201  * This is the recommended mode of operation. This calculates the digest
202  * and send the digest to the server. The digest is only calculated on
203  * the client, and not on the server.
204  */
206 
207  /**
208  * Send the key, but do not store it.
209  *
210  * This policy is ideal if you want to reduce the number of bytes sent
211  * over the network. This will only work if the combination the set and
212  * key value are less than 20 bytes, which is the size of the digest.
213  *
214  * This will also cause the digest to be computer once on the client
215  * and once on the server.
216  *
217  * If your values are not less than 20 bytes, then you should just
218  * use AS_POLICY_KEY_DIGEST.
219  */
221 
222  /**
223  * Store the key.
224  * @warning Not yet implemented
225  */
227 
228 } as_policy_key;
229 
230 /**
231  * Existence Policy.
232  *
233  * Specifies the behavior for writing the record
234  * depending whether or not it exists.
235  *
236  * @ingroup client_policies
237  */
238 typedef enum as_policy_exists_e {
239 
240  /**
241  * The policy is undefined.
242  *
243  * If set, then the value will default to
244  * either as_config.policies.exists
245  * or `AS_POLICY_EXISTS_DEFAULT`.
246  */
248 
249  /**
250  * Write the record, regardless of existence. (i.e. create or update.)
251  */
253 
254  /**
255  * Create a record, ONLY if it doesn't exist.
256  */
258 
259  /**
260  * Update a record, ONLY if it exists.
261  */
263 
264  /**
265  * Completely replace a record, ONLY if it exists.
266  */
268 
269  /**
270  * Completely replace a record if it exists, otherwise create it.
271  */
273 
275 
276 /**
277  * Write Policy
278  *
279  * @ingroup client_policies
280  */
281 typedef struct as_policy_write_s {
282 
283  /**
284  * Maximum time in milliseconds to wait for
285  * the operation to complete.
286  *
287  * If 0 (zero), then the value will default to
288  * either as_config.policies.timeout
289  * or `AS_POLICY_TIMEOUT_DEFAULT`.
290  */
291  uint32_t timeout;
292 
293  /**
294  * Specifies the behavior for failed operations.
295  */
297 
298  /**
299  * Specifies the behavior for the key.
300  */
302 
303  /**
304  * Specifies the behavior for the generation
305  * value.
306  */
308 
309  /**
310  * Specifies the behavior for the existence
311  * of the record.
312  */
314 
316 
317 /**
318  * Read Policy
319  *
320  * @ingroup client_policies
321  */
322 typedef struct as_policy_read_s {
323 
324  /**
325  * Maximum time in milliseconds to wait for
326  * the operation to complete.
327  *
328  * If 0 (zero), then the value will default to
329  * either as_config.policies.timeout
330  * or `AS_POLICY_TIMEOUT_DEFAULT`.
331  */
332  uint32_t timeout;
333 
334  /**
335  * Specifies the behavior for the key.
336  */
338 
340 
341 /**
342  * Key Apply Policy
343  *
344  * @ingroup client_policies
345  */
346 typedef struct as_policy_apply_s {
347 
348  /**
349  * Maximum time in milliseconds to wait for
350  * the operation to complete.
351  *
352  * If 0 (zero), then the value will default to
353  * either as_config.policies.timeout
354  * or `AS_POLICY_TIMEOUT_DEFAULT`.
355  */
356  uint32_t timeout;
357 
358  /**
359  * Specifies the behavior for the key.
360  */
362 
364 
365 /**
366  * Operate Policy
367  *
368  * @ingroup client_policies
369  */
370 typedef struct as_policy_operate_s {
371 
372  /**
373  * Maximum time in milliseconds to wait for
374  * the operation to complete.
375  *
376  * If 0 (zero), then the value will default to
377  * either as_config.policies.timeout
378  * or `AS_POLICY_TIMEOUT_DEFAULT`.
379  */
380  uint32_t timeout;
381 
382  /**
383  * Specifies the behavior for failed operations.
384  */
386 
387  /**
388  * Specifies the behavior for the key.
389  */
391 
392  /**
393  * Specifies the behavior for the generation
394  * value.
395  */
397 
399 
400 /**
401  * Remove Policy
402  *
403  * @ingroup client_policies
404  */
405 typedef struct as_policy_remove_s {
406 
407  /**
408  * Maximum time in milliseconds to wait for
409  * the operation to complete.
410  *
411  * If 0 (zero), then the value will default to
412  * either as_config.policies.timeout
413  * or `AS_POLICY_TIMEOUT_DEFAULT`.
414  */
415  uint32_t timeout;
416 
417  /**
418  * The generation of the record.
419  */
420  uint16_t generation;
421 
422  /**
423  * Specifies the behavior of failed operations.
424  */
426 
427  /**
428  * Specifies the behavior for the key.
429  */
431 
432  /**
433  * Specifies the behavior for the generation
434  * value.
435  */
437 
439 
440 /**
441  * Query Policy
442  *
443  * @ingroup client_policies
444  */
445 typedef struct as_policy_query_s {
446 
447  /**
448  * Maximum time in milliseconds to wait for
449  * the operation to complete.
450  *
451  * If 0 (zero), then the value will default to
452  * either as_config.policies.timeout
453  * or Aerospike's recommended default.
454  */
455  uint32_t timeout;
456 
458 
459 /**
460  * Scan Policy
461  *
462  * @ingroup client_policies
463  */
464 typedef struct as_policy_scan_s {
465 
466  /**
467  * Maximum time in milliseconds to wait for the operation to complete.
468  *
469  * If 0 (zero), then the value will default to
470  * either as_config.policies.timeout
471  * or `AS_POLICY_TIMEOUT_DEFAULT`.
472  */
473  uint32_t timeout;
474 
475  /**
476  * Abort the scan if the cluster is not in a
477  * stable state.
478  */
480 
482 
483 /**
484  * Info Policy
485  *
486  * @ingroup client_policies
487  */
488 typedef struct as_policy_info_s {
489 
490  /**
491  * Maximum time in milliseconds to wait for
492  * the operation to complete.
493  *
494  * If 0 (zero), then the value will default to
495  * either as_config.policies.timeout
496  * or `AS_POLICY_TIMEOUT_DEFAULT`.
497  */
498  uint32_t timeout;
499 
500  /**
501  * Send request without any further processing.
502  */
504 
505  /**
506  * Ensure the request is within allowable size limits.
507  */
509 
511 
512 /**
513  * Batch Policy
514  *
515  * @ingroup client_policies
516  */
517 typedef struct as_policy_batch_s {
518 
519  /**
520  * Maximum time in milliseconds to wait for
521  * the operation to complete.
522  *
523  * If 0 (zero), then the value will default to
524  * either as_config.policies.timeout
525  * or `AS_POLICY_TIMEOUT_DEFAULT`.
526  */
527  uint32_t timeout;
528 
530 
531 /**
532  * Struct of all policy values and operation policies.
533  *
534  * This is utilizes by as_config, to define global and default values
535  * for policies.
536  *
537  * @ingroup as_config_t
538  */
539 typedef struct as_policies_s {
540 
541  /***************************************************************************
542  * DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
543  **************************************************************************/
544 
545  /**
546  * Default timeout in milliseconds.
547  *
548  * Will be used if specific policies have a timeout of 0 (zero).
549  *
550  * The default value is `AS_POLICY_TIMEOUT_DEFAULT`.
551  */
552  uint32_t timeout;
553 
554  /**
555  * Specifies the behavior for failed operations.
556  *
557  * The default value is `AS_POLICY_RETRY_DEFAULT`.
558  */
560 
561  /**
562  * Specifies the behavior for the key.
563  *
564  * The default value is `AS_POLICY_KEY_DEFAULT`.
565  */
567 
568  /**
569  * Specifies the behavior for the generation
570  * value.
571  *
572  * The default value is `AS_POLICY_GEN_DEFAULT`.
573  */
575 
576  /**
577  * Specifies the behavior for the existence
578  * of the record.
579  *
580  * The default value is `AS_POLICY_EXISTS_DEFAULT`.
581  */
583 
584  /***************************************************************************
585  * SPECIFIC POLICIES
586  **************************************************************************/
587 
588  /**
589  * The default read policy.
590  */
592 
593  /**
594  * The default write policy.
595  */
597 
598  /**
599  * The default operate policy.
600  */
602 
603  /**
604  * The default remove policy.
605  */
607 
608  /**
609  * The default apply policy.
610  */
612 
613  /**
614  * The default query policy.
615  */
617 
618  /**
619  * The default scan policy.
620  */
622 
623  /**
624  * The default info policy.
625  */
627 
628  /**
629  * The default batch policy.
630  */
632 
633 } as_policies;
634 
635 /******************************************************************************
636  * FUNCTIONS
637  *****************************************************************************/
638 
639 /**
640  * Initialize as_policy_read to default values.
641  *
642  * @param p The policy to initialize
643  * @return The initialized policy.
644  *
645  * @relates as_policy_read
646  */
648 
649 /**
650  * Initialize as_policy_apply to default values.
651  *
652  * @param p The policy to initialize
653  * @return The initialized policy.
654  *
655  * @relates as_policy_apply
656  */
658 
659 /**
660  * Initialize as_policy_write to default values.
661  *
662  * @param p The policy to initialize
663  * @return The initialized policy.
664  *
665  * @relates as_policy_write
666  */
668 
669 /**
670  * Initialize as_policy_operate to default values.
671  *
672  * @param p The policy to initialize
673  * @return The initialized policy.
674  *
675  * @relates as_policy_operate
676  */
678 
679 /**
680  * Initialize as_policy_scan to default values.
681  *
682  * @param p The policy to initialize
683  * @return The initialized policy.
684  *
685  * @relates as_policy_scan
686  */
688 
689 /**
690  * Initialize as_policy_query to default values.
691  *
692  * @param p The policy to initialize
693  * @return The initialized policy.
694  *
695  * @relates as_policy_query
696  */
698 
699 /**
700  * Initialize as_policy_info to default values.
701  *
702  * @param p The policy to initialize
703  * @return The initialized policy.
704  *
705  * @relates as_policy_info
706  */
708 
709 /**
710  * Initialize as_policy_remove to default values.
711  *
712  * @param p The policy to initialize
713  * @return The initialized policy.
714  *
715  * @relates as_policy_remove
716  */
718 
719 /**
720  * Initialize as_policy_batch to default values.
721  *
722  * @param p The policy to initialize
723  * @return The initialized policy.
724  *
725  * @relates as_policy_batch
726  */
728 
729 /**
730  * Initialize as_policies to default values.
731  *
732  * @param p The policies to initialize
733  * @return The initialized policies.
734  *
735  * @relates as_policies
736  */
738 
739