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, in addition to the digest value.
209  *
210  * If you want keys to be returned when scanning or querying, the keys must
211  * be stored on the server. This policy causes a write operation to store
212  * the key. Once a key is stored, the server will keep it - there is no
213  * need to use this policy on subsequent updates of the record.
214  *
215  * If this policy is used on read or delete operations, or on subsequent
216  * updates of a record with a stored key, the key sent will be compared
217  * with the key stored on the server. A mismatch will cause
218  * AEROSPIKE_ERR_RECORD_KEY_MISMATCH to be returned.
219  */
221 
222 } as_policy_key;
223 
224 /**
225  * Existence Policy.
226  *
227  * Specifies the behavior for writing the record
228  * depending whether or not it exists.
229  *
230  * @ingroup client_policies
231  */
232 typedef enum as_policy_exists_e {
233 
234  /**
235  * The policy is undefined.
236  *
237  * If set, then the value will default to
238  * either as_config.policies.exists
239  * or `AS_POLICY_EXISTS_DEFAULT`.
240  */
242 
243  /**
244  * Write the record, regardless of existence. (i.e. create or update.)
245  */
247 
248  /**
249  * Create a record, ONLY if it doesn't exist.
250  */
252 
253  /**
254  * Update a record, ONLY if it exists.
255  */
257 
258  /**
259  * Completely replace a record, ONLY if it exists.
260  */
262 
263  /**
264  * Completely replace a record if it exists, otherwise create it.
265  */
267 
269 
270 /**
271  * Boolean Policy.
272  *
273  * This enum provides boolean values (true,false) and an
274  * undefined value for the boolean.
275  *
276  * @ingroup client_policies
277  */
278 typedef enum as_policy_bool_e {
279 
280  /**
281  * If the value is neither true or false,
282  * then it is undefined. This is used for cases
283  * where we initialize a variable, but do not want
284  * it to have a value.
285  */
287 
288  /**
289  * This value is interchangable with `false`.
290  */
292 
293  /**
294  * This value is interchangable with `true`.
295  */
297 
299 
300 
301 /**
302  * Write Policy
303  *
304  * @ingroup client_policies
305  */
306 typedef struct as_policy_write_s {
307 
308  /**
309  * Maximum time in milliseconds to wait for
310  * the operation to complete.
311  *
312  * If 0 (zero), then the value will default to
313  * either as_config.policies.timeout
314  * or `AS_POLICY_TIMEOUT_DEFAULT`.
315  */
316  uint32_t timeout;
317 
318  /**
319  * Specifies the behavior for failed operations.
320  */
322 
323  /**
324  * Specifies the behavior for the key.
325  */
327 
328  /**
329  * Specifies the behavior for the generation
330  * value.
331  */
333 
334  /**
335  * Specifies the behavior for the existence
336  * of the record.
337  */
339 
341 
342 /**
343  * Read Policy
344  *
345  * @ingroup client_policies
346  */
347 typedef struct as_policy_read_s {
348 
349  /**
350  * Maximum time in milliseconds to wait for
351  * the operation to complete.
352  *
353  * If 0 (zero), then the value will default to
354  * either as_config.policies.timeout
355  * or `AS_POLICY_TIMEOUT_DEFAULT`.
356  */
357  uint32_t timeout;
358 
359  /**
360  * Specifies the behavior for the key.
361  */
363 
365 
366 /**
367  * Key Apply Policy
368  *
369  * @ingroup client_policies
370  */
371 typedef struct as_policy_apply_s {
372 
373  /**
374  * Maximum time in milliseconds to wait for
375  * the operation to complete.
376  *
377  * If 0 (zero), then the value will default to
378  * either as_config.policies.timeout
379  * or `AS_POLICY_TIMEOUT_DEFAULT`.
380  */
381  uint32_t timeout;
382 
383  /**
384  * Specifies the behavior for the key.
385  */
387 
389 
390 /**
391  * Operate Policy
392  *
393  * @ingroup client_policies
394  */
395 typedef struct as_policy_operate_s {
396 
397  /**
398  * Maximum time in milliseconds to wait for
399  * the operation to complete.
400  *
401  * If 0 (zero), then the value will default to
402  * either as_config.policies.timeout
403  * or `AS_POLICY_TIMEOUT_DEFAULT`.
404  */
405  uint32_t timeout;
406 
407  /**
408  * Specifies the behavior for failed operations.
409  */
411 
412  /**
413  * Specifies the behavior for the key.
414  */
416 
417  /**
418  * Specifies the behavior for the generation
419  * value.
420  */
422 
424 
425 /**
426  * Remove Policy
427  *
428  * @ingroup client_policies
429  */
430 typedef struct as_policy_remove_s {
431 
432  /**
433  * Maximum time in milliseconds to wait for
434  * the operation to complete.
435  *
436  * If 0 (zero), then the value will default to
437  * either as_config.policies.timeout
438  * or `AS_POLICY_TIMEOUT_DEFAULT`.
439  */
440  uint32_t timeout;
441 
442  /**
443  * The generation of the record.
444  */
445  uint16_t generation;
446 
447  /**
448  * Specifies the behavior of failed operations.
449  */
451 
452  /**
453  * Specifies the behavior for the key.
454  */
456 
457  /**
458  * Specifies the behavior for the generation
459  * value.
460  */
462 
464 
465 /**
466  * Query Policy
467  *
468  * @ingroup client_policies
469  */
470 typedef struct as_policy_query_s {
471 
472  /**
473  * Maximum time in milliseconds to wait for
474  * the operation to complete.
475  *
476  * If 0 (zero), then the value will default to
477  * either as_config.policies.timeout
478  * or Aerospike's recommended default.
479  */
480  uint32_t timeout;
481 
483 
484 /**
485  * Scan Policy
486  *
487  * @ingroup client_policies
488  */
489 typedef struct as_policy_scan_s {
490 
491  /**
492  * Maximum time in milliseconds to wait for 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  * Abort the scan if the cluster is not in a
502  * stable state.
503  */
505 
507 
508 /**
509  * Info Policy
510  *
511  * @ingroup client_policies
512  */
513 typedef struct as_policy_info_s {
514 
515  /**
516  * Maximum time in milliseconds to wait for
517  * the operation to complete.
518  *
519  * If 0 (zero), then the value will default to
520  * either as_config.policies.timeout
521  * or `AS_POLICY_TIMEOUT_DEFAULT`.
522  */
523  uint32_t timeout;
524 
525  /**
526  * Send request without any further processing.
527  */
529 
530  /**
531  * Ensure the request is within allowable size limits.
532  */
534 
536 
537 /**
538  * Batch Policy
539  *
540  * @ingroup client_policies
541  */
542 typedef struct as_policy_batch_s {
543 
544  /**
545  * Maximum time in milliseconds to wait for
546  * the operation to complete.
547  *
548  * If 0 (zero), then the value will default to
549  * either as_config.policies.timeout
550  * or `AS_POLICY_TIMEOUT_DEFAULT`.
551  */
552  uint32_t timeout;
553 
555 
556 /**
557  * Administration Policy
558  *
559  * @ingroup client_policies
560  */
561 typedef struct as_policy_admin_s {
562 
563  /**
564  * Maximum time in milliseconds to wait for
565  * the operation to complete.
566  *
567  * If 0 (zero), then the value will default to
568  * either as_config.policies.timeout
569  * or `AS_POLICY_TIMEOUT_DEFAULT`.
570  */
571  uint32_t timeout;
572 
574 
575 /**
576  * Struct of all policy values and operation policies.
577  *
578  * This is utilizes by as_config, to define global and default values
579  * for policies.
580  *
581  * @ingroup as_config_t
582  */
583 typedef struct as_policies_s {
584 
585  /***************************************************************************
586  * DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
587  **************************************************************************/
588 
589  /**
590  * Default timeout in milliseconds.
591  *
592  * Will be used if specific policies have a timeout of 0 (zero).
593  *
594  * The default value is `AS_POLICY_TIMEOUT_DEFAULT`.
595  */
596  uint32_t timeout;
597 
598  /**
599  * Specifies the behavior for failed operations.
600  *
601  * The default value is `AS_POLICY_RETRY_DEFAULT`.
602  */
604 
605  /**
606  * Specifies the behavior for the key.
607  *
608  * The default value is `AS_POLICY_KEY_DEFAULT`.
609  */
611 
612  /**
613  * Specifies the behavior for the generation
614  * value.
615  *
616  * The default value is `AS_POLICY_GEN_DEFAULT`.
617  */
619 
620  /**
621  * Specifies the behavior for the existence
622  * of the record.
623  *
624  * The default value is `AS_POLICY_EXISTS_DEFAULT`.
625  */
627 
628  /***************************************************************************
629  * SPECIFIC POLICIES
630  **************************************************************************/
631 
632  /**
633  * The default read policy.
634  */
636 
637  /**
638  * The default write policy.
639  */
641 
642  /**
643  * The default operate policy.
644  */
646 
647  /**
648  * The default remove policy.
649  */
651 
652  /**
653  * The default apply policy.
654  */
656 
657  /**
658  * The default query policy.
659  */
661 
662  /**
663  * The default scan policy.
664  */
666 
667  /**
668  * The default info policy.
669  */
671 
672  /**
673  * The default batch policy.
674  */
676 
677  /**
678  * The default administration policy.
679  */
681 
682 } as_policies;
683 
684 /******************************************************************************
685  * FUNCTIONS
686  *****************************************************************************/
687 
688 /**
689  * Initialize as_policy_read to default values.
690  *
691  * @param p The policy to initialize
692  * @return The initialized policy.
693  *
694  * @relates as_policy_read
695  */
697 
698 /**
699  * Initialize as_policy_apply to default values.
700  *
701  * @param p The policy to initialize
702  * @return The initialized policy.
703  *
704  * @relates as_policy_apply
705  */
707 
708 /**
709  * Initialize as_policy_write to default values.
710  *
711  * @param p The policy to initialize
712  * @return The initialized policy.
713  *
714  * @relates as_policy_write
715  */
717 
718 /**
719  * Initialize as_policy_operate to default values.
720  *
721  * @param p The policy to initialize
722  * @return The initialized policy.
723  *
724  * @relates as_policy_operate
725  */
727 
728 /**
729  * Initialize as_policy_scan to default values.
730  *
731  * @param p The policy to initialize
732  * @return The initialized policy.
733  *
734  * @relates as_policy_scan
735  */
737 
738 /**
739  * Initialize as_policy_query to default values.
740  *
741  * @param p The policy to initialize
742  * @return The initialized policy.
743  *
744  * @relates as_policy_query
745  */
747 
748 /**
749  * Initialize as_policy_info to default values.
750  *
751  * @param p The policy to initialize
752  * @return The initialized policy.
753  *
754  * @relates as_policy_info
755  */
757 
758 /**
759  * Initialize as_policy_remove to default values.
760  *
761  * @param p The policy to initialize
762  * @return The initialized policy.
763  *
764  * @relates as_policy_remove
765  */
767 
768 /**
769  * Initialize as_policy_batch to default values.
770  *
771  * @param p The policy to initialize
772  * @return The initialized policy.
773  *
774  * @relates as_policy_batch
775  */
777 
778 /**
779  * Initialize as_policy_admin to default values.
780  *
781  * @param p The policy to initialize
782  * @return The initialized policy.
783  *
784  * @relates as_policy_admin
785  */
787 
788 /**
789  * Initialize as_policies to default values.
790  *
791  * @param p The policies to initialize
792  * @return The initialized policies.
793  *
794  * @relates as_policies
795  */
797 
798 
as_policy_info * as_policy_info_init(as_policy_info *p)
as_policy_bool
Definition: as_policy.h:278
as_policy_key
Definition: as_policy.h:188
uint32_t timeout
Definition: as_policy.h:381
as_policy_remove * as_policy_remove_init(as_policy_remove *p)
as_policy_scan scan
Definition: as_policy.h:665
as_policy_bool check_bounds
Definition: as_policy.h:533
as_policy_admin admin
Definition: as_policy.h:680
as_policy_key key
Definition: as_policy.h:362
as_policy_gen gen
Definition: as_policy.h:461
as_policy_gen
Definition: as_policy.h:145
as_policy_retry
Definition: as_policy.h:113
as_policy_key key
Definition: as_policy.h:455
uint32_t timeout
Definition: as_policy.h:571
as_policy_query * as_policy_query_init(as_policy_query *p)
as_policy_key key
Definition: as_policy.h:415
uint32_t timeout
Definition: as_policy.h:552
as_policy_write * as_policy_write_init(as_policy_write *p)
as_policy_exists
Definition: as_policy.h:232
uint32_t timeout
Definition: as_policy.h:480
as_policy_info info
Definition: as_policy.h:670
as_policy_write write
Definition: as_policy.h:640
as_policy_apply apply
Definition: as_policy.h:655
uint32_t timeout
Definition: as_policy.h:523
uint32_t timeout
Definition: as_policy.h:316
as_policy_apply * as_policy_apply_init(as_policy_apply *p)
uint32_t timeout
Definition: as_policy.h:357
as_policy_query query
Definition: as_policy.h:660
as_policy_operate operate
Definition: as_policy.h:645
as_policy_admin * as_policy_admin_init(as_policy_admin *p)
as_policy_retry retry
Definition: as_policy.h:603
as_policy_operate * as_policy_operate_init(as_policy_operate *p)
as_policies * as_policies_init(as_policies *p)
as_policy_key key
Definition: as_policy.h:610
as_policy_key key
Definition: as_policy.h:386
uint32_t timeout
Definition: as_policy.h:596
as_policy_gen gen
Definition: as_policy.h:618
as_policy_gen gen
Definition: as_policy.h:421
as_policy_bool send_as_is
Definition: as_policy.h:528
as_policy_retry retry
Definition: as_policy.h:450
as_policy_batch * as_policy_batch_init(as_policy_batch *p)
as_policy_read * as_policy_read_init(as_policy_read *p)
uint32_t timeout
Definition: as_policy.h:440
as_policy_read read
Definition: as_policy.h:635
as_policy_exists exists
Definition: as_policy.h:626
as_policy_batch batch
Definition: as_policy.h:675
uint32_t timeout
Definition: as_policy.h:498
as_policy_exists exists
Definition: as_policy.h:338
uint32_t timeout
Definition: as_policy.h:405
as_policy_key key
Definition: as_policy.h:326
as_policy_scan * as_policy_scan_init(as_policy_scan *p)
as_policy_gen gen
Definition: as_policy.h:332
as_policy_bool fail_on_cluster_change
Definition: as_policy.h:504
as_policy_retry retry
Definition: as_policy.h:321
as_policy_retry retry
Definition: as_policy.h:410
uint16_t generation
Definition: as_policy.h:445