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 
54 #include <stdbool.h>
55 #include <stdint.h>
56 
57 /******************************************************************************
58  * MACROS
59  *****************************************************************************/
60 
61 /**
62  * Default timeout value
63  *
64  * @ingroup client_policies
65  */
66 #define AS_POLICY_TIMEOUT_DEFAULT 1000
67 
68 /**
69  * Default as_policy_retry value
70  *
71  * @ingroup client_policies
72  */
73 #define AS_POLICY_RETRY_DEFAULT AS_POLICY_RETRY_NONE
74 
75 /**
76  * Default as_policy_gen value
77  *
78  * @ingroup client_policies
79  */
80 #define AS_POLICY_GEN_DEFAULT AS_POLICY_GEN_IGNORE
81 
82 /**
83  * Default as_policy_key value
84  *
85  * @ingroup client_policies
86  */
87 #define AS_POLICY_KEY_DEFAULT AS_POLICY_KEY_DIGEST
88 
89 /**
90  * Default as_policy_exists value
91  *
92  * @ingroup client_policies
93  */
94 #define AS_POLICY_EXISTS_DEFAULT AS_POLICY_EXISTS_IGNORE
95 
96 /******************************************************************************
97  * TYPES
98  *****************************************************************************/
99 
100 /**
101  * Retry Policy
102  *
103  * Specifies the behavior of failed operations.
104  *
105  * @ingroup client_policies
106  */
107 typedef enum as_policy_retry_e {
108 
109  /**
110  * The policy is undefined.
111  *
112  * If set, then the value will default to
113  * either as_config.policies.retry
114  * or `AS_POLICY_RETRY_DEFAULT`.
115  */
117 
118  /**
119  * Only attempt an operation once.
120  */
122 
123  /**
124  * If an operation fails, attempt the operation
125  * one more time.
126  */
128 
130 
131 /**
132  * Generation Policy
133  *
134  * Specifies the behavior of record modifications with regard to the
135  * generation value.
136  *
137  * @ingroup client_policies
138  */
139 typedef enum as_policy_gen_e {
140 
141  /**
142  * The policy is undefined.
143  *
144  * If set, then the value will default to
145  * either as_config.policies.gen
146  * or `AS_POLICY_GEN_DEFAULT`.
147  */
149 
150  /**
151  * Write a record, regardless of generation.
152  */
154 
155  /**
156  * Write a record, ONLY if generations are equal
157  */
159 
160  /**
161  * Write a record, ONLY if local generation is
162  * greater-than remote generation
163  */
165 
166  /**
167  * Write a record creating a duplicate, ONLY if
168  * the generation collides (?)
169  */
171 
172 } as_policy_gen;
173 
174 /**
175  * Key Policy
176  *
177  * Specifies the behavior for whether keys or digests
178  * should be sent to the cluster.
179  *
180  * @ingroup client_policies
181  */
182 typedef enum as_policy_key_e {
183 
184  /**
185  * The policy is undefined.
186  *
187  * If set, then the value will default to either as_config.policies.key
188  * or `AS_POLICY_KEY_DEFAULT`.
189  */
191 
192  /**
193  * Send the digest value of the key.
194  *
195  * This is the recommended mode of operation. This calculates the digest
196  * and send the digest to the server. The digest is only calculated on
197  * the client, and not on the server.
198  */
200 
201  /**
202  * Send the key, in addition to the digest value.
203  *
204  * If you want keys to be returned when scanning or querying, the keys must
205  * be stored on the server. This policy causes a write operation to store
206  * the key. Once a key is stored, the server will keep it - there is no
207  * need to use this policy on subsequent updates of the record.
208  *
209  * If this policy is used on read or delete operations, or on subsequent
210  * updates of a record with a stored key, the key sent will be compared
211  * with the key stored on the server. A mismatch will cause
212  * AEROSPIKE_ERR_RECORD_KEY_MISMATCH to be returned.
213  */
215 
216 } as_policy_key;
217 
218 /**
219  * Existence Policy.
220  *
221  * Specifies the behavior for writing the record
222  * depending whether or not it exists.
223  *
224  * @ingroup client_policies
225  */
226 typedef enum as_policy_exists_e {
227 
228  /**
229  * The policy is undefined.
230  *
231  * If set, then the value will default to
232  * either as_config.policies.exists
233  * or `AS_POLICY_EXISTS_DEFAULT`.
234  */
236 
237  /**
238  * Write the record, regardless of existence. (i.e. create or update.)
239  */
241 
242  /**
243  * Create a record, ONLY if it doesn't exist.
244  */
246 
247  /**
248  * Update a record, ONLY if it exists.
249  */
251 
252  /**
253  * Completely replace a record, ONLY if it exists.
254  */
256 
257  /**
258  * Completely replace a record if it exists, otherwise create it.
259  */
261 
263 
264 /**
265  * Boolean Policy.
266  *
267  * This enum provides boolean values (true,false) and an
268  * undefined value for the boolean.
269  *
270  * @ingroup client_policies
271  */
272 typedef enum as_policy_bool_e {
273 
274  /**
275  * If the value is neither true or false,
276  * then it is undefined. This is used for cases
277  * where we initialize a variable, but do not want
278  * it to have a value.
279  */
281 
282  /**
283  * This value is interchangable with `false`.
284  */
286 
287  /**
288  * This value is interchangable with `true`.
289  */
291 
293 
294 
295 /**
296  * Write Policy
297  *
298  * @ingroup client_policies
299  */
300 typedef struct as_policy_write_s {
301 
302  /**
303  * Maximum time in milliseconds to wait for
304  * the operation to complete.
305  *
306  * If 0 (zero), then the value will default to
307  * either as_config.policies.timeout
308  * or `AS_POLICY_TIMEOUT_DEFAULT`.
309  */
310  uint32_t timeout;
311 
312  /**
313  * Specifies the behavior for failed operations.
314  */
316 
317  /**
318  * Specifies the behavior for the key.
319  */
321 
322  /**
323  * Specifies the behavior for the generation
324  * value.
325  */
327 
328  /**
329  * Specifies the behavior for the existence
330  * of the record.
331  */
333 
335 
336 /**
337  * Read Policy
338  *
339  * @ingroup client_policies
340  */
341 typedef struct as_policy_read_s {
342 
343  /**
344  * Maximum time in milliseconds to wait for
345  * the operation to complete.
346  *
347  * If 0 (zero), then the value will default to
348  * either as_config.policies.timeout
349  * or `AS_POLICY_TIMEOUT_DEFAULT`.
350  */
351  uint32_t timeout;
352 
353  /**
354  * Specifies the behavior for the key.
355  */
357 
359 
360 /**
361  * Key Apply Policy
362  *
363  * @ingroup client_policies
364  */
365 typedef struct as_policy_apply_s {
366 
367  /**
368  * Maximum time in milliseconds to wait for
369  * the operation to complete.
370  *
371  * If 0 (zero), then the value will default to
372  * either as_config.policies.timeout
373  * or `AS_POLICY_TIMEOUT_DEFAULT`.
374  */
375  uint32_t timeout;
376 
377  /**
378  * Specifies the behavior for the key.
379  */
381 
383 
384 /**
385  * Operate Policy
386  *
387  * @ingroup client_policies
388  */
389 typedef struct as_policy_operate_s {
390 
391  /**
392  * Maximum time in milliseconds to wait for
393  * the operation to complete.
394  *
395  * If 0 (zero), then the value will default to
396  * either as_config.policies.timeout
397  * or `AS_POLICY_TIMEOUT_DEFAULT`.
398  */
399  uint32_t timeout;
400 
401  /**
402  * Specifies the behavior for failed operations.
403  */
405 
406  /**
407  * Specifies the behavior for the key.
408  */
410 
411  /**
412  * Specifies the behavior for the generation
413  * value.
414  */
416 
418 
419 /**
420  * Remove Policy
421  *
422  * @ingroup client_policies
423  */
424 typedef struct as_policy_remove_s {
425 
426  /**
427  * Maximum time in milliseconds to wait for
428  * the operation to complete.
429  *
430  * If 0 (zero), then the value will default to
431  * either as_config.policies.timeout
432  * or `AS_POLICY_TIMEOUT_DEFAULT`.
433  */
434  uint32_t timeout;
435 
436  /**
437  * The generation of the record.
438  */
439  uint16_t generation;
440 
441  /**
442  * Specifies the behavior of failed operations.
443  */
445 
446  /**
447  * Specifies the behavior for the key.
448  */
450 
451  /**
452  * Specifies the behavior for the generation
453  * value.
454  */
456 
458 
459 /**
460  * Query Policy
461  *
462  * @ingroup client_policies
463  */
464 typedef struct as_policy_query_s {
465 
466  /**
467  * Maximum time in milliseconds to wait for
468  * the operation to complete.
469  *
470  * If 0 (zero), then the value will default to
471  * either as_config.policies.timeout
472  * or Aerospike's recommended default.
473  */
474  uint32_t timeout;
475 
477 
478 /**
479  * Scan Policy
480  *
481  * @ingroup client_policies
482  */
483 typedef struct as_policy_scan_s {
484 
485  /**
486  * Maximum time in milliseconds to wait for the operation to complete.
487  *
488  * If 0 (zero), then the value will default to
489  * either as_config.policies.timeout
490  * or `AS_POLICY_TIMEOUT_DEFAULT`.
491  */
492  uint32_t timeout;
493 
494  /**
495  * Abort the scan if the cluster is not in a
496  * stable state.
497  */
499 
501 
502 /**
503  * Info Policy
504  *
505  * @ingroup client_policies
506  */
507 typedef struct as_policy_info_s {
508 
509  /**
510  * Maximum time in milliseconds to wait for
511  * the operation to complete.
512  *
513  * If 0 (zero), then the value will default to
514  * either as_config.policies.timeout
515  * or `AS_POLICY_TIMEOUT_DEFAULT`.
516  */
517  uint32_t timeout;
518 
519  /**
520  * Send request without any further processing.
521  */
523 
524  /**
525  * Ensure the request is within allowable size limits.
526  */
528 
530 
531 /**
532  * Batch Policy
533  *
534  * @ingroup client_policies
535  */
536 typedef struct as_policy_batch_s {
537 
538  /**
539  * Maximum time in milliseconds to wait for
540  * the operation to complete.
541  *
542  * If 0 (zero), then the value will default to
543  * either as_config.policies.timeout
544  * or `AS_POLICY_TIMEOUT_DEFAULT`.
545  */
546  uint32_t timeout;
547 
549 
550 /**
551  * Administration Policy
552  *
553  * @ingroup client_policies
554  */
555 typedef struct as_policy_admin_s {
556 
557  /**
558  * Maximum time in milliseconds to wait for
559  * the operation to complete.
560  *
561  * If 0 (zero), then the value will default to
562  * either as_config.policies.timeout
563  * or `AS_POLICY_TIMEOUT_DEFAULT`.
564  */
565  uint32_t timeout;
566 
568 
569 /**
570  * Struct of all policy values and operation policies.
571  *
572  * This is utilizes by as_config, to define global and default values
573  * for policies.
574  *
575  * @ingroup as_config_t
576  */
577 typedef struct as_policies_s {
578 
579  /***************************************************************************
580  * DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
581  **************************************************************************/
582 
583  /**
584  * Default timeout in milliseconds.
585  *
586  * Will be used if specific policies have a timeout of 0 (zero).
587  *
588  * The default value is `AS_POLICY_TIMEOUT_DEFAULT`.
589  */
590  uint32_t timeout;
591 
592  /**
593  * Specifies the behavior for failed operations.
594  *
595  * The default value is `AS_POLICY_RETRY_DEFAULT`.
596  */
598 
599  /**
600  * Specifies the behavior for the key.
601  *
602  * The default value is `AS_POLICY_KEY_DEFAULT`.
603  */
605 
606  /**
607  * Specifies the behavior for the generation
608  * value.
609  *
610  * The default value is `AS_POLICY_GEN_DEFAULT`.
611  */
613 
614  /**
615  * Specifies the behavior for the existence
616  * of the record.
617  *
618  * The default value is `AS_POLICY_EXISTS_DEFAULT`.
619  */
621 
622  /***************************************************************************
623  * SPECIFIC POLICIES
624  **************************************************************************/
625 
626  /**
627  * The default read policy.
628  */
630 
631  /**
632  * The default write policy.
633  */
635 
636  /**
637  * The default operate policy.
638  */
640 
641  /**
642  * The default remove policy.
643  */
645 
646  /**
647  * The default apply policy.
648  */
650 
651  /**
652  * The default query policy.
653  */
655 
656  /**
657  * The default scan policy.
658  */
660 
661  /**
662  * The default info policy.
663  */
665 
666  /**
667  * The default batch policy.
668  */
670 
671  /**
672  * The default administration policy.
673  */
675 
676 } as_policies;
677 
678 /******************************************************************************
679  * FUNCTIONS
680  *****************************************************************************/
681 
682 /**
683  * Initialize as_policy_read to default values.
684  *
685  * @param p The policy to initialize
686  * @return The initialized policy.
687  *
688  * @relates as_policy_read
689  */
691 
692 /**
693  * Initialize as_policy_apply to default values.
694  *
695  * @param p The policy to initialize
696  * @return The initialized policy.
697  *
698  * @relates as_policy_apply
699  */
701 
702 /**
703  * Initialize as_policy_write to default values.
704  *
705  * @param p The policy to initialize
706  * @return The initialized policy.
707  *
708  * @relates as_policy_write
709  */
711 
712 /**
713  * Initialize as_policy_operate to default values.
714  *
715  * @param p The policy to initialize
716  * @return The initialized policy.
717  *
718  * @relates as_policy_operate
719  */
721 
722 /**
723  * Initialize as_policy_scan to default values.
724  *
725  * @param p The policy to initialize
726  * @return The initialized policy.
727  *
728  * @relates as_policy_scan
729  */
731 
732 /**
733  * Initialize as_policy_query to default values.
734  *
735  * @param p The policy to initialize
736  * @return The initialized policy.
737  *
738  * @relates as_policy_query
739  */
741 
742 /**
743  * Initialize as_policy_info to default values.
744  *
745  * @param p The policy to initialize
746  * @return The initialized policy.
747  *
748  * @relates as_policy_info
749  */
751 
752 /**
753  * Initialize as_policy_remove to default values.
754  *
755  * @param p The policy to initialize
756  * @return The initialized policy.
757  *
758  * @relates as_policy_remove
759  */
761 
762 /**
763  * Initialize as_policy_batch to default values.
764  *
765  * @param p The policy to initialize
766  * @return The initialized policy.
767  *
768  * @relates as_policy_batch
769  */
771 
772 /**
773  * Initialize as_policy_admin to default values.
774  *
775  * @param p The policy to initialize
776  * @return The initialized policy.
777  *
778  * @relates as_policy_admin
779  */
781 
782 /**
783  * Initialize as_policies to default values.
784  *
785  * @param p The policies to initialize
786  * @return The initialized policies.
787  *
788  * @relates as_policies
789  */
791 
792