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-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  * @defgroup client_policies Client Policies
21  *
22  * Policies define the behavior of database operations.
23  *
24  * Policies fall into two groups: policy values and operation policies.
25  * A policy value is a single value which defines how the client behaves. An
26  * operation policy is a group of policy values which affect an operation.
27  *
28  * ## Policy Values
29  *
30  * The following are the policy values. For details, please see the documentation
31  * for each policy value
32  *
33  * - as_policy_key
34  * - as_policy_gen
35  * - as_policy_retry
36  * - as_policy_exists
37  *
38  * ## Operation Policies
39  *
40  * The following are the operation policies. Operation policies are groups of
41  * policy values for a type of operation.
42  *
43  * - as_policy_batch
44  * - as_policy_info
45  * - as_policy_operate
46  * - as_policy_read
47  * - as_policy_remove
48  * - as_policy_query
49  * - as_policy_scan
50  * - as_policy_write
51  */
52 
53 #include <stdbool.h>
54 #include <stdint.h>
55 
56 /******************************************************************************
57  * MACROS
58  *****************************************************************************/
59 
60 /**
61  * Default timeout value
62  *
63  * @ingroup client_policies
64  */
65 #define AS_POLICY_TIMEOUT_DEFAULT 1000
66 
67 /**
68  * Default as_policy_retry value
69  *
70  * @ingroup client_policies
71  */
72 #define AS_POLICY_RETRY_DEFAULT AS_POLICY_RETRY_ONCE
73 
74 /**
75  * Default as_policy_gen value
76  *
77  * @ingroup client_policies
78  */
79 #define AS_POLICY_GEN_DEFAULT AS_POLICY_GEN_IGNORE
80 
81 /**
82  * Default as_policy_key value
83  *
84  * @ingroup client_policies
85  */
86 #define AS_POLICY_KEY_DEFAULT AS_POLICY_KEY_DIGEST
87 
88 /**
89  * Default as_policy_exists value
90  *
91  * @ingroup client_policies
92  */
93 #define AS_POLICY_EXISTS_DEFAULT AS_POLICY_EXISTS_IGNORE
94 
95 /******************************************************************************
96  * TYPES
97  *****************************************************************************/
98 
99 /**
100  * Retry Policy
101  *
102  * Specifies the behavior of failed operations.
103  *
104  * @ingroup client_policies
105  */
106 typedef enum as_policy_retry_e {
107 
108  /**
109  * Only attempt an operation once.
110  */
112 
113  /**
114  * If an operation fails, attempt the operation
115  * one more time.
116  */
118 
120 
121 /**
122  * Generation Policy
123  *
124  * Specifies the behavior of record modifications with regard to the
125  * generation value.
126  *
127  * @ingroup client_policies
128  */
129 typedef enum as_policy_gen_e {
130 
131  /**
132  * Write a record, regardless of generation.
133  */
135 
136  /**
137  * Write a record, ONLY if generations are equal
138  */
140 
141  /**
142  * Write a record, ONLY if local generation is
143  * greater-than remote generation
144  */
146 
147  /**
148  * Write a record creating a duplicate, ONLY if
149  * the generation collides (?)
150  */
152 
153 } as_policy_gen;
154 
155 /**
156  * Key Policy
157  *
158  * Specifies the behavior for whether keys or digests
159  * should be sent to the cluster.
160  *
161  * @ingroup client_policies
162  */
163 typedef enum as_policy_key_e {
164 
165  /**
166  * Send the digest value of the key.
167  *
168  * This is the recommended mode of operation. This calculates the digest
169  * and send the digest to the server. The digest is only calculated on
170  * the client, and not on the server.
171  */
173 
174  /**
175  * Send the key, in addition to the digest value.
176  *
177  * If you want keys to be returned when scanning or querying, the keys must
178  * be stored on the server. This policy causes a write operation to store
179  * the key. Once a key is stored, the server will keep it - there is no
180  * need to use this policy on subsequent updates of the record.
181  *
182  * If this policy is used on read or delete operations, or on subsequent
183  * updates of a record with a stored key, the key sent will be compared
184  * with the key stored on the server. A mismatch will cause
185  * AEROSPIKE_ERR_RECORD_KEY_MISMATCH to be returned.
186  */
188 
189 } as_policy_key;
190 
191 /**
192  * Existence Policy.
193  *
194  * Specifies the behavior for writing the record
195  * depending whether or not it exists.
196  *
197  * @ingroup client_policies
198  */
199 typedef enum as_policy_exists_e {
200 
201  /**
202  * Write the record, regardless of existence. (i.e. create or update.)
203  */
205 
206  /**
207  * Create a record, ONLY if it doesn't exist.
208  */
210 
211  /**
212  * Update a record, ONLY if it exists.
213  */
215 
216  /**
217  * Completely replace a record, ONLY if it exists.
218  */
220 
221  /**
222  * Completely replace a record if it exists, otherwise create it.
223  */
225 
227 
228 /**
229  * Write Policy
230  *
231  * @ingroup client_policies
232  */
233 typedef struct as_policy_write_s {
234 
235  /**
236  * Maximum time in milliseconds to wait for
237  * the operation to complete.
238  *
239  * If undefined (-1), then the value will default to
240  * either as_config.policies.timeout
241  * or `AS_POLICY_TIMEOUT_DEFAULT`.
242  */
243  uint32_t timeout;
244 
245  /**
246  * Specifies the behavior for failed operations.
247  */
249 
250  /**
251  * Specifies the behavior for the key.
252  */
254 
255  /**
256  * Specifies the behavior for the generation
257  * value.
258  */
260 
261  /**
262  * Specifies the behavior for the existence
263  * of the record.
264  */
266 
268 
269 /**
270  * Read Policy
271  *
272  * @ingroup client_policies
273  */
274 typedef struct as_policy_read_s {
275 
276  /**
277  * Maximum time in milliseconds to wait for
278  * the operation to complete.
279  *
280  * If undefined (-1), then the value will default to
281  * either as_config.policies.timeout
282  * or `AS_POLICY_TIMEOUT_DEFAULT`.
283  */
284  uint32_t timeout;
285 
286  /**
287  * Specifies the behavior for the key.
288  */
290 
292 
293 /**
294  * Key Apply Policy
295  *
296  * @ingroup client_policies
297  */
298 typedef struct as_policy_apply_s {
299 
300  /**
301  * Maximum time in milliseconds to wait for
302  * the operation to complete.
303  *
304  * If undefined (-1), then the value will default to
305  * either as_config.policies.timeout
306  * or `AS_POLICY_TIMEOUT_DEFAULT`.
307  */
308  uint32_t timeout;
309 
310  /**
311  * Specifies the behavior for the key.
312  */
314 
316 
317 /**
318  * Operate Policy
319  *
320  * @ingroup client_policies
321  */
322 typedef struct as_policy_operate_s {
323 
324  /**
325  * Maximum time in milliseconds to wait for
326  * the operation to complete.
327  *
328  * If undefined (-1), 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 failed operations.
336  */
338 
339  /**
340  * Specifies the behavior for the key.
341  */
343 
344  /**
345  * Specifies the behavior for the generation
346  * value.
347  */
349 
351 
352 /**
353  * Remove Policy
354  *
355  * @ingroup client_policies
356  */
357 typedef struct as_policy_remove_s {
358 
359  /**
360  * Maximum time in milliseconds to wait for
361  * the operation to complete.
362  *
363  * If undefined (-1), then the value will default to
364  * either as_config.policies.timeout
365  * or `AS_POLICY_TIMEOUT_DEFAULT`.
366  */
367  uint32_t timeout;
368 
369  /**
370  * The generation of the record.
371  */
372  uint16_t generation;
373 
374  /**
375  * Specifies the behavior of failed operations.
376  */
378 
379  /**
380  * Specifies the behavior for the key.
381  */
383 
384  /**
385  * Specifies the behavior for the generation
386  * value.
387  */
389 
391 
392 /**
393  * Query Policy
394  *
395  * @ingroup client_policies
396  */
397 typedef struct as_policy_query_s {
398 
399  /**
400  * Maximum time in milliseconds to wait for
401  * the operation to complete.
402  *
403  * The default (0) means do not timeout.
404  */
405  uint32_t timeout;
406 
408 
409 /**
410  * Scan Policy
411  *
412  * @ingroup client_policies
413  */
414 typedef struct as_policy_scan_s {
415 
416  /**
417  * Maximum time in milliseconds to wait for the operation to complete.
418  *
419  * The default (0) means do not timeout.
420  */
421  uint32_t timeout;
422 
423  /**
424  * Abort the scan if the cluster is not in a
425  * stable state.
426  */
428 
430 
431 /**
432  * Info Policy
433  *
434  * @ingroup client_policies
435  */
436 typedef struct as_policy_info_s {
437 
438  /**
439  * Maximum time in milliseconds to wait for
440  * the operation to complete.
441  *
442  * If undefined (-1), then the value will default to
443  * either as_config.policies.timeout
444  * or `AS_POLICY_TIMEOUT_DEFAULT`.
445  */
446  uint32_t timeout;
447 
448  /**
449  * Send request without any further processing.
450  */
452 
453  /**
454  * Ensure the request is within allowable size limits.
455  */
457 
459 
460 /**
461  * Batch Policy
462  *
463  * @ingroup client_policies
464  */
465 typedef struct as_policy_batch_s {
466 
467  /**
468  * Maximum time in milliseconds to wait for
469  * the operation to complete.
470  *
471  * If undefined (-1), then the value will default to
472  * either as_config.policies.timeout
473  * or `AS_POLICY_TIMEOUT_DEFAULT`.
474  */
475  uint32_t timeout;
476 
478 
479 /**
480  * Administration Policy
481  *
482  * @ingroup client_policies
483  */
484 typedef struct as_policy_admin_s {
485 
486  /**
487  * Maximum time in milliseconds to wait for
488  * the operation to complete.
489  *
490  * If undefined (-1), then the value will default to
491  * either as_config.policies.timeout
492  * or `AS_POLICY_TIMEOUT_DEFAULT`.
493  */
494  uint32_t timeout;
495 
497 
498 /**
499  * Struct of all policy values and operation policies.
500  *
501  * This is utilizes by as_config, to define global and default values
502  * for policies.
503  *
504  * @ingroup as_config_t
505  */
506 typedef struct as_policies_s {
507 
508  /***************************************************************************
509  * DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
510  **************************************************************************/
511 
512  /**
513  * Default timeout in milliseconds.
514  *
515  * Will be used if specific policies have a timeout of 0 (zero).
516  *
517  * The default value is `AS_POLICY_TIMEOUT_DEFAULT`.
518  */
519  uint32_t timeout;
520 
521  /**
522  * Specifies the behavior for failed operations.
523  *
524  * The default value is `AS_POLICY_RETRY_DEFAULT`.
525  */
527 
528  /**
529  * Specifies the behavior for the key.
530  *
531  * The default value is `AS_POLICY_KEY_DEFAULT`.
532  */
534 
535  /**
536  * Specifies the behavior for the generation
537  * value.
538  *
539  * The default value is `AS_POLICY_GEN_DEFAULT`.
540  */
542 
543  /**
544  * Specifies the behavior for the existence
545  * of the record.
546  *
547  * The default value is `AS_POLICY_EXISTS_DEFAULT`.
548  */
550 
551  /***************************************************************************
552  * SPECIFIC POLICIES
553  **************************************************************************/
554 
555  /**
556  * The default read policy.
557  */
559 
560  /**
561  * The default write policy.
562  */
564 
565  /**
566  * The default operate policy.
567  */
569 
570  /**
571  * The default remove policy.
572  */
574 
575  /**
576  * The default apply policy.
577  */
579 
580  /**
581  * The default query policy.
582  */
584 
585  /**
586  * The default scan policy.
587  */
589 
590  /**
591  * The default info policy.
592  */
594 
595  /**
596  * The default batch policy.
597  */
599 
600  /**
601  * The default administration policy.
602  */
604 
605 } as_policies;
606 
607 /******************************************************************************
608  * FUNCTIONS
609  *****************************************************************************/
610 
611 /**
612  * Initialize as_policy_read to default values.
613  *
614  * @param p The policy to initialize.
615  * @return The initialized policy.
616  *
617  * @relates as_policy_read
618  */
619 static inline as_policy_read*
621 {
624  return p;
625 }
626 
627 /**
628  * Copy as_policy_read values.
629  *
630  * @param src The source policy.
631  * @param trg The target policy.
632  *
633  * @relates as_policy_read
634  */
635 static inline void
637 {
638  trg->timeout = src->timeout;
639  trg->key = src->key;
640 }
641 
642 /**
643  * Initialize as_policy_write to default values.
644  *
645  * @param p The policy to initialize.
646  * @return The initialized policy.
647  *
648  * @relates as_policy_write
649  */
650 static inline as_policy_write*
652 {
658  return p;
659 }
660 
661 /**
662  * Copy as_policy_write values.
663  *
664  * @param src The source policy.
665  * @param trg The target policy.
666  *
667  * @relates as_policy_write
668  */
669 static inline void
671 {
672  trg->timeout = src->timeout;
673  trg->retry = src->retry;
674  trg->key = src->key;
675  trg->gen = src->gen;
676  trg->exists = src->exists;
677 }
678 
679 /**
680  * Initialize as_policy_operate to default values.
681  *
682  * @param p The policy to initialize.
683  * @return The initialized policy.
684  *
685  * @relates as_policy_operate
686  */
687 static inline as_policy_operate*
689 {
694  return p;
695 }
696 
697 /**
698  * Copy as_policy_operate values.
699  *
700  * @param src The source policy.
701  * @param trg The target policy.
702  *
703  * @relates as_policy_operate
704  */
705 static inline void
707 {
708  trg->timeout = src->timeout;
709  trg->retry = src->retry;
710  trg->key = src->key;
711  trg->gen = src->gen;
712 }
713 
714 /**
715  * Initialize as_policy_remove to default values.
716  *
717  * @param p The policy to initialize.
718  * @return The initialized policy.
719  *
720  * @relates as_policy_remove
721  */
722 static inline as_policy_remove*
724 {
729  p->generation = 0;
730  return p;
731 }
732 
733 /**
734  * Copy as_policy_remove values.
735  *
736  * @param src The source policy.
737  * @param trg The target policy.
738  *
739  * @relates as_policy_remove
740  */
741 static inline void
743 {
744  trg->timeout = src->timeout;
745  trg->retry = src->retry;
746  trg->key = src->key;
747  trg->gen = src->gen;
748  trg->generation = src->generation;
749 }
750 
751 /**
752  * Initialize as_policy_apply to default values.
753  *
754  * @param p The policy to initialize.
755  * @return The initialized policy.
756  *
757  * @relates as_policy_apply
758  */
759 static inline as_policy_apply*
761 {
764  return p;
765 }
766 
767 /**
768  * Copy as_policy_apply values.
769  *
770  * @param src The source policy.
771  * @param trg The target policy.
772  *
773  * @relates as_policy_apply
774  */
775 static inline void
777 {
778  trg->timeout = src->timeout;
779  trg->key = src->key;
780 }
781 
782 /**
783  * Initialize as_policy_info to default values.
784  *
785  * @param p The policy to initialize.
786  * @return The initialized policy.
787  *
788  * @relates as_policy_info
789  */
790 static inline as_policy_info*
792 {
794  p->send_as_is = true;
795  p->check_bounds = true;
796  return p;
797 }
798 
799 /**
800  * Copy as_policy_info values.
801  *
802  * @param src The source policy.
803  * @param trg The target policy.
804  *
805  * @relates as_policy_info
806  */
807 static inline void
809 {
810  trg->timeout = src->timeout;
811  trg->send_as_is = src->send_as_is;
812  trg->check_bounds = src->check_bounds;
813 }
814 
815 /**
816  * Initialize as_policy_batch to default values.
817  *
818  * @param p The policy to initialize.
819  * @return The initialized policy.
820  *
821  * @relates as_policy_batch
822  */
823 static inline as_policy_batch*
825 {
827  return p;
828 }
829 
830 /**
831  * Copy as_policy_batch values.
832  *
833  * @param src The source policy.
834  * @param trg The target policy.
835  *
836  * @relates as_policy_batch
837  */
838 static inline void
840 {
841  trg->timeout = src->timeout;
842 }
843 
844 /**
845  * Initialize as_policy_admin to default values.
846  *
847  * @param p The policy to initialize.
848  * @return The initialized policy.
849  *
850  * @relates as_policy_admin
851  */
852 static inline as_policy_admin*
854 {
856  return p;
857 }
858 
859 /**
860  * Copy as_policy_admin values.
861  *
862  * @param src The source policy.
863  * @param trg The target policy.
864  *
865  * @relates as_policy_admin
866  */
867 static inline void
869 {
870  trg->timeout = src->timeout;
871 }
872 
873 /**
874  * Initialize as_policy_scan to default values.
875  *
876  * @param p The policy to initialize.
877  * @return The initialized policy.
878  *
879  * @relates as_policy_scan
880  */
881 static inline as_policy_scan*
883 {
884  p->timeout = 0;
885  p->fail_on_cluster_change = false;
886  return p;
887 }
888 
889 /**
890  * Copy as_policy_scan values.
891  *
892  * @param src The source policy.
893  * @param trg The target policy.
894  *
895  * @relates as_policy_scan
896  */
897 static inline void
899 {
900  trg->timeout = src->timeout;
902 }
903 
904 /**
905  * Initialize as_policy_query to default values.
906  *
907  * @param p The policy to initialize.
908  * @return The initialized policy.
909  *
910  * @relates as_policy_query
911  */
912 static inline as_policy_query*
914 {
915  p->timeout = 0;
916  return p;
917 }
918 
919 /**
920  * Copy as_policy_query values.
921  *
922  * @param src The source policy.
923  * @param trg The target policy.
924  *
925  * @relates as_policy_query
926  */
927 static inline void
929 {
930  trg->timeout = src->timeout;
931 }
932 
933 /**
934  * Initialize as_policies to undefined values.
935  * as_policies_resolve() will later be called resolve undefined values to global defaults.
936  *
937  * @param p The policies to undefine
938  * @return The undefined policies.
939  *
940  * @relates as_policies
941  */
944 
945 /**
946  * Resolve global policies (like timeout) with operational policies (like as_policy_read).
947  *
948  * @param p The policies to resolve
949  *
950  * @relates as_policies
951  */
952 void