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  * 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  * Boolean Policy.
278  *
279  * This enum provides boolean values (true,false) and an
280  * undefined value for the boolean.
281  *
282  * @ingroup client_policies
283  */
284 typedef enum as_policy_bool_e {
285 
286  /**
287  * If the value is neither true or false,
288  * then it is undefined. This is used for cases
289  * where we initialize a variable, but do not want
290  * it to have a value.
291  */
293 
294  /**
295  * This value is interchangable with `false`.
296  */
298 
299  /**
300  * This value is interchangable with `true`.
301  */
303 
305 
306 
307 /**
308  * Write Policy
309  *
310  * @ingroup client_policies
311  */
312 typedef struct as_policy_write_s {
313 
314  /**
315  * Maximum time in milliseconds to wait for
316  * the operation to complete.
317  *
318  * If 0 (zero), then the value will default to
319  * either as_config.policies.timeout
320  * or `AS_POLICY_TIMEOUT_DEFAULT`.
321  */
322  uint32_t timeout;
323 
324  /**
325  * Specifies the behavior for failed operations.
326  */
327  as_policy_retry retry;
328 
329  /**
330  * Specifies the behavior for the key.
331  */
333 
334  /**
335  * Specifies the behavior for the generation
336  * value.
337  */
338  as_policy_gen gen;
339 
340  /**
341  * Specifies the behavior for the existence
342  * of the record.
343  */
344  as_policy_exists exists;
345 
347 
348 /**
349  * Read Policy
350  *
351  * @ingroup client_policies
352  */
353 typedef struct as_policy_read_s {
354 
355  /**
356  * Maximum time in milliseconds to wait for
357  * the operation to complete.
358  *
359  * If 0 (zero), then the value will default to
360  * either as_config.policies.timeout
361  * or `AS_POLICY_TIMEOUT_DEFAULT`.
362  */
363  uint32_t timeout;
364 
365  /**
366  * Specifies the behavior for the key.
367  */
369 
371 
372 /**
373  * Key Apply Policy
374  *
375  * @ingroup client_policies
376  */
377 typedef struct as_policy_apply_s {
378 
379  /**
380  * Maximum time in milliseconds to wait for
381  * the operation to complete.
382  *
383  * If 0 (zero), then the value will default to
384  * either as_config.policies.timeout
385  * or `AS_POLICY_TIMEOUT_DEFAULT`.
386  */
387  uint32_t timeout;
388 
389  /**
390  * Specifies the behavior for the key.
391  */
393 
395 
396 /**
397  * Operate Policy
398  *
399  * @ingroup client_policies
400  */
401 typedef struct as_policy_operate_s {
402 
403  /**
404  * Maximum time in milliseconds to wait for
405  * the operation to complete.
406  *
407  * If 0 (zero), then the value will default to
408  * either as_config.policies.timeout
409  * or `AS_POLICY_TIMEOUT_DEFAULT`.
410  */
411  uint32_t timeout;
412 
413  /**
414  * Specifies the behavior for failed operations.
415  */
416  as_policy_retry retry;
417 
418  /**
419  * Specifies the behavior for the key.
420  */
422 
423  /**
424  * Specifies the behavior for the generation
425  * value.
426  */
427  as_policy_gen gen;
428 
430 
431 /**
432  * Remove Policy
433  *
434  * @ingroup client_policies
435  */
436 typedef struct as_policy_remove_s {
437 
438  /**
439  * Maximum time in milliseconds to wait for
440  * the operation to complete.
441  *
442  * If 0 (zero), 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  * The generation of the record.
450  */
451  uint16_t generation;
452 
453  /**
454  * Specifies the behavior of failed operations.
455  */
456  as_policy_retry retry;
457 
458  /**
459  * Specifies the behavior for the key.
460  */
462 
463  /**
464  * Specifies the behavior for the generation
465  * value.
466  */
467  as_policy_gen gen;
468 
470 
471 /**
472  * Query Policy
473  *
474  * @ingroup client_policies
475  */
476 typedef struct as_policy_query_s {
477 
478  /**
479  * Maximum time in milliseconds to wait for
480  * the operation to complete.
481  *
482  * If 0 (zero), then the value will default to
483  * either as_config.policies.timeout
484  * or Aerospike's recommended default.
485  */
486  uint32_t timeout;
487 
489 
490 /**
491  * Scan Policy
492  *
493  * @ingroup client_policies
494  */
495 typedef struct as_policy_scan_s {
496 
497  /**
498  * Maximum time in milliseconds to wait for the operation to complete.
499  *
500  * If 0 (zero), then the value will default to
501  * either as_config.policies.timeout
502  * or `AS_POLICY_TIMEOUT_DEFAULT`.
503  */
504  uint32_t timeout;
505 
506  /**
507  * Abort the scan if the cluster is not in a
508  * stable state.
509  */
510  as_policy_bool fail_on_cluster_change;
511 
513 
514 /**
515  * Info Policy
516  *
517  * @ingroup client_policies
518  */
519 typedef struct as_policy_info_s {
520 
521  /**
522  * Maximum time in milliseconds to wait for
523  * the operation to complete.
524  *
525  * If 0 (zero), then the value will default to
526  * either as_config.policies.timeout
527  * or `AS_POLICY_TIMEOUT_DEFAULT`.
528  */
529  uint32_t timeout;
530 
531  /**
532  * Send request without any further processing.
533  */
534  as_policy_bool send_as_is;
535 
536  /**
537  * Ensure the request is within allowable size limits.
538  */
539  as_policy_bool check_bounds;
540 
542 
543 /**
544  * Batch Policy
545  *
546  * @ingroup client_policies
547  */
548 typedef struct as_policy_batch_s {
549 
550  /**
551  * Maximum time in milliseconds to wait for
552  * the operation to complete.
553  *
554  * If 0 (zero), then the value will default to
555  * either as_config.policies.timeout
556  * or `AS_POLICY_TIMEOUT_DEFAULT`.
557  */
558  uint32_t timeout;
559 
561 
562 /**
563  * Struct of all policy values and operation policies.
564  *
565  * This is utilizes by as_config, to define global and default values
566  * for policies.
567  *
568  * @ingroup as_config_t
569  */
570 typedef struct as_policies_s {
571 
572  /***************************************************************************
573  * DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
574  **************************************************************************/
575 
576  /**
577  * Default timeout in milliseconds.
578  *
579  * Will be used if specific policies have a timeout of 0 (zero).
580  *
581  * The default value is `AS_POLICY_TIMEOUT_DEFAULT`.
582  */
583  uint32_t timeout;
584 
585  /**
586  * Specifies the behavior for failed operations.
587  *
588  * The default value is `AS_POLICY_RETRY_DEFAULT`.
589  */
590  as_policy_retry retry;
591 
592  /**
593  * Specifies the behavior for the key.
594  *
595  * The default value is `AS_POLICY_KEY_DEFAULT`.
596  */
598 
599  /**
600  * Specifies the behavior for the generation
601  * value.
602  *
603  * The default value is `AS_POLICY_GEN_DEFAULT`.
604  */
605  as_policy_gen gen;
606 
607  /**
608  * Specifies the behavior for the existence
609  * of the record.
610  *
611  * The default value is `AS_POLICY_EXISTS_DEFAULT`.
612  */
613  as_policy_exists exists;
614 
615  /***************************************************************************
616  * SPECIFIC POLICIES
617  **************************************************************************/
618 
619  /**
620  * The default read policy.
621  */
622  as_policy_read read;
623 
624  /**
625  * The default write policy.
626  */
627  as_policy_write write;
628 
629  /**
630  * The default operate policy.
631  */
632  as_policy_operate operate;
633 
634  /**
635  * The default remove policy.
636  */
637  as_policy_remove remove;
638 
639  /**
640  * The default apply policy.
641  */
642  as_policy_apply apply;
643 
644  /**
645  * The default query policy.
646  */
647  as_policy_query query;
648 
649  /**
650  * The default scan policy.
651  */
652  as_policy_scan scan;
653 
654  /**
655  * The default info policy.
656  */
658 
659  /**
660  * The default batch policy.
661  */
662  as_policy_batch batch;
663 
664 } as_policies;
665 
666 /******************************************************************************
667  * FUNCTIONS
668  *****************************************************************************/
669 
670 /**
671  * Initialize as_policy_read to default values.
672  *
673  * @param p The policy to initialize
674  * @return The initialized policy.
675  *
676  * @relates as_policy_read
677  */
679 
680 /**
681  * Initialize as_policy_apply to default values.
682  *
683  * @param p The policy to initialize
684  * @return The initialized policy.
685  *
686  * @relates as_policy_apply
687  */
689 
690 /**
691  * Initialize as_policy_write to default values.
692  *
693  * @param p The policy to initialize
694  * @return The initialized policy.
695  *
696  * @relates as_policy_write
697  */
699 
700 /**
701  * Initialize as_policy_operate to default values.
702  *
703  * @param p The policy to initialize
704  * @return The initialized policy.
705  *
706  * @relates as_policy_operate
707  */
709 
710 /**
711  * Initialize as_policy_scan to default values.
712  *
713  * @param p The policy to initialize
714  * @return The initialized policy.
715  *
716  * @relates as_policy_scan
717  */
719 
720 /**
721  * Initialize as_policy_query to default values.
722  *
723  * @param p The policy to initialize
724  * @return The initialized policy.
725  *
726  * @relates as_policy_query
727  */
729 
730 /**
731  * Initialize as_policy_info to default values.
732  *
733  * @param p The policy to initialize
734  * @return The initialized policy.
735  *
736  * @relates as_policy_info
737  */
739 
740 /**
741  * Initialize as_policy_remove to default values.
742  *
743  * @param p The policy to initialize
744  * @return The initialized policy.
745  *
746  * @relates as_policy_remove
747  */
749 
750 /**
751  * Initialize as_policy_batch to default values.
752  *
753  * @param p The policy to initialize
754  * @return The initialized policy.
755  *
756  * @relates as_policy_batch
757  */
759 
760 /**
761  * Initialize as_policies to default values.
762  *
763  * @param p The policies to initialize
764  * @return The initialized policies.
765  *
766  * @relates as_policies
767  */
769 
770