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