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, 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_KEY_DDEFAULT`.
246  */
248 
249  /**
250  * Write the record, regardless of existence.
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  * @warning Not yet implemented
262  */
264 
266 
267 /**
268  * Write Policy
269  *
270  * @ingroup client_policies
271  */
272 typedef struct as_policy_write_s {
273 
274  /**
275  * Maximum time in milliseconds to wait for
276  * the operation to complete.
277  *
278  * If 0 (zero), then the value will default to
279  * either as_config.policies.timeout
280  * or `AS_POLICY_TIMEOUT_DEFAULT`.
281  */
282  uint32_t timeout;
283 
284  /**
285  * Specifies the behavior for failed operations.
286  */
288 
289  /**
290  * Specifies the behavior for the key.
291  */
293 
294  /**
295  * Specifies the behavior for the generation
296  * value.
297  */
299 
300  /**
301  * Specifies the behavior for the existence
302  * of the record.
303  */
305 
307 
308 /**
309  * Read Policy
310  *
311  * @ingroup client_policies
312  */
313 typedef struct as_policy_read_s {
314 
315  /**
316  * Maximum time in milliseconds to wait for
317  * the operation to complete.
318  *
319  * If 0 (zero), then the value will default to
320  * either as_config.policies.timeout
321  * or `AS_POLICY_TIMEOUT_DEFAULT`.
322  */
323  uint32_t timeout;
324 
325  /**
326  * Specifies the behavior for the key.
327  */
329 
331 
332 /**
333  * Key Apply Policy
334  *
335  * @ingroup client_policies
336  */
337 typedef struct as_policy_apply_s {
338 
339  /**
340  * Maximum time in milliseconds to wait for
341  * the operation to complete.
342  *
343  * If 0 (zero), then the value will default to
344  * either as_config.policies.timeout
345  * or `AS_POLICY_TIMEOUT_DEFAULT`.
346  */
347  uint32_t timeout;
348 
349  /**
350  * Specifies the behavior for the key.
351  */
353 
355 
356 /**
357  * Operate Policy
358  *
359  * @ingroup client_policies
360  */
361 typedef struct as_policy_operate_s {
362 
363  /**
364  * Maximum time in milliseconds to wait for
365  * the operation to complete.
366  *
367  * If 0 (zero), then the value will default to
368  * either as_config.policies.timeout
369  * or `AS_POLICY_TIMEOUT_DEFAULT`.
370  */
371  uint32_t timeout;
372 
373  /**
374  * Specifies the behavior for failed operations.
375  */
377 
378  /**
379  * Specifies the behavior for the key.
380  */
382 
383  /**
384  * Specifies the behavior for the generation
385  * value.
386  */
388 
390 
391 /**
392  * Remove Policy
393  *
394  * @ingroup client_policies
395  */
396 typedef struct as_policy_remove_s {
397 
398  /**
399  * Maximum time in milliseconds to wait for
400  * the operation to complete.
401  *
402  * If 0 (zero), then the value will default to
403  * either as_config.policies.timeout
404  * or `AS_POLICY_TIMEOUT_DEFAULT`.
405  */
406  uint32_t timeout;
407 
408  /**
409  * The generation of the record.
410  */
411  uint16_t generation;
412 
413  /**
414  * Specifies the behavior of failed operations.
415  */
417 
418  /**
419  * Specifies the behavior for the key.
420  */
422 
423  /**
424  * Specifies the behavior for the generation
425  * value.
426  */
428 
430 
431 /**
432  * Query Policy
433  *
434  * @ingroup client_policies
435  */
436 typedef struct as_policy_query_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 Aerospike's recommended default.
445  */
446  uint32_t timeout;
447 
449 
450 /**
451  * Scan Policy
452  *
453  * @ingroup client_policies
454  */
455 typedef struct as_policy_scan_s {
456 
457  /**
458  * Maximum time in milliseconds to wait for the operation to complete.
459  *
460  * If 0 (zero), then the value will default to
461  * either as_config.policies.timeout
462  * or `AS_POLICY_TIMEOUT_DEFAULT`.
463  */
464  uint32_t timeout;
465 
466  /**
467  * Abort the scan if the cluster is not in a
468  * stable state.
469  */
471 
473 
474 /**
475  * Info Policy
476  *
477  * @ingroup client_policies
478  */
479 typedef struct as_policy_info_s {
480 
481  /**
482  * Maximum time in milliseconds to wait for
483  * the operation to complete.
484  *
485  * If 0 (zero), then the value will default to
486  * either as_config.policies.timeout
487  * or `AS_POLICY_TIMEOUT_DEFAULT`.
488  */
489  uint32_t timeout;
490 
491  /**
492  * Send request without any further processing.
493  */
495 
496  /**
497  * Ensure the request is within allowable size limits.
498  */
500 
502 
503 /**
504  * Batch Policy
505  *
506  * @ingroup client_policies
507  */
508 typedef struct as_policy_batch_s {
509 
510  /**
511  * Maximum time in milliseconds to wait for
512  * the operation to complete.
513  *
514  * If 0 (zero), then the value will default to
515  * either as_config.policies.timeout
516  * or `AS_POLICY_TIMEOUT_DEFAULT`.
517  */
518  uint32_t timeout;
519 
521 
522 /**
523  * Struct of all policy values and operation policies.
524  *
525  * This is utilizes by as_config, to define global and default values
526  * for policies.
527  *
528  * @ingroup as_config_t
529  */
530 typedef struct as_policies_s {
531 
532  /***************************************************************************
533  * DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
534  **************************************************************************/
535 
536  /**
537  * Default timeout in milliseconds.
538  *
539  * Will be used if specific policies have a timeout of 0 (zero).
540  *
541  * The default value is `AS_POLICY_TIMEOUT_DEFAULT`.
542  */
543  uint32_t timeout;
544 
545  /**
546  * Specifies the behavior for failed operations.
547  *
548  * The default value is `AS_POLICY_RETRY_DEFAULT`.
549  */
551 
552  /**
553  * Specifies the behavior for the key.
554  *
555  * The default value is `AS_POLICY_KEY_DEFAULT`.
556  */
558 
559  /**
560  * Specifies the behavior for the generation
561  * value.
562  *
563  * The default value is `AS_POLICY_GEN_DEFAULT`.
564  */
566 
567  /**
568  * Specifies the behavior for the existence
569  * of the record.
570  *
571  * The default value is `AS_POLICY_EXISTS_DEFAULT`.
572  */
574 
575  /***************************************************************************
576  * SPECIFIC POLICIES
577  **************************************************************************/
578 
579  /**
580  * The default read policy.
581  */
583 
584  /**
585  * The default write policy.
586  */
588 
589  /**
590  * The default operate policy.
591  */
593 
594  /**
595  * The default remove policy.
596  */
598 
599  /**
600  * The default apply policy.
601  */
603 
604  /**
605  * The default query policy.
606  */
608 
609  /**
610  * The default scan policy.
611  */
613 
614  /**
615  * The default info policy.
616  */
618 
619  /**
620  * The default batch policy.
621  */
623 
624 } as_policies;
625 
626 /******************************************************************************
627  * FUNCTIONS
628  *****************************************************************************/
629 
630 /**
631  * Initialize as_policy_read to default values.
632  *
633  * @param p The policy to initialize
634  * @return The initialized policy.
635  *
636  * @relates as_policy_read
637  */
639 
640 /**
641  * Initialize as_policy_apply to default values.
642  *
643  * @param p The policy to initialize
644  * @return The initialized policy.
645  *
646  * @relates as_policy_apply
647  */
649 
650 /**
651  * Initialize as_policy_write to default values.
652  *
653  * @param p The policy to initialize
654  * @return The initialized policy.
655  *
656  * @relates as_policy_write
657  */
659 
660 /**
661  * Initialize as_policy_operate to default values.
662  *
663  * @param p The policy to initialize
664  * @return The initialized policy.
665  *
666  * @relates as_policy_operate
667  */
669 
670 /**
671  * Initialize as_policy_scan to default values.
672  *
673  * @param p The policy to initialize
674  * @return The initialized policy.
675  *
676  * @relates as_policy_scan
677  */
679 
680 /**
681  * Initialize as_policy_query to default values.
682  *
683  * @param p The policy to initialize
684  * @return The initialized policy.
685  *
686  * @relates as_policy_query
687  */
689 
690 /**
691  * Initialize as_policy_info to default values.
692  *
693  * @param p The policy to initialize
694  * @return The initialized policy.
695  *
696  * @relates as_policy_info
697  */
699 
700 /**
701  * Initialize as_policy_remove to default values.
702  *
703  * @param p The policy to initialize
704  * @return The initialized policy.
705  *
706  * @relates as_policy_remove
707  */
709 
710 /**
711  * Initialize as_policy_batch to default values.
712  *
713  * @param p The policy to initialize
714  * @return The initialized policy.
715  *
716  * @relates as_policy_batch
717  */
719 
720 /**
721  * Initialize as_policies to default values.
722  *
723  * @param p The policies to initialize
724  * @return The initialized policies.
725  *
726  * @relates as_policies
727  */
729 
730