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_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 if it exists, otherwise create it.
266  */
268 
270 
271 /**
272  * Write Policy
273  *
274  * @ingroup client_policies
275  */
276 typedef struct as_policy_write_s {
277 
278  /**
279  * Maximum time in milliseconds to wait for
280  * the operation to complete.
281  *
282  * If 0 (zero), then the value will default to
283  * either as_config.policies.timeout
284  * or `AS_POLICY_TIMEOUT_DEFAULT`.
285  */
286  uint32_t timeout;
287 
288  /**
289  * Specifies the behavior for failed operations.
290  */
292 
293  /**
294  * Specifies the behavior for the key.
295  */
297 
298  /**
299  * Specifies the behavior for the generation
300  * value.
301  */
303 
304  /**
305  * Specifies the behavior for the existence
306  * of the record.
307  */
309 
311 
312 /**
313  * Read Policy
314  *
315  * @ingroup client_policies
316  */
317 typedef struct as_policy_read_s {
318 
319  /**
320  * Maximum time in milliseconds to wait for
321  * the operation to complete.
322  *
323  * If 0 (zero), then the value will default to
324  * either as_config.policies.timeout
325  * or `AS_POLICY_TIMEOUT_DEFAULT`.
326  */
327  uint32_t timeout;
328 
329  /**
330  * Specifies the behavior for the key.
331  */
333 
335 
336 /**
337  * Key Apply Policy
338  *
339  * @ingroup client_policies
340  */
341 typedef struct as_policy_apply_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  * Operate Policy
362  *
363  * @ingroup client_policies
364  */
365 typedef struct as_policy_operate_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 failed operations.
379  */
381 
382  /**
383  * Specifies the behavior for the key.
384  */
386 
387  /**
388  * Specifies the behavior for the generation
389  * value.
390  */
392 
394 
395 /**
396  * Remove Policy
397  *
398  * @ingroup client_policies
399  */
400 typedef struct as_policy_remove_s {
401 
402  /**
403  * Maximum time in milliseconds to wait for
404  * the operation to complete.
405  *
406  * If 0 (zero), then the value will default to
407  * either as_config.policies.timeout
408  * or `AS_POLICY_TIMEOUT_DEFAULT`.
409  */
410  uint32_t timeout;
411 
412  /**
413  * The generation of the record.
414  */
415  uint16_t generation;
416 
417  /**
418  * Specifies the behavior of failed operations.
419  */
421 
422  /**
423  * Specifies the behavior for the key.
424  */
426 
427  /**
428  * Specifies the behavior for the generation
429  * value.
430  */
432 
434 
435 /**
436  * Query Policy
437  *
438  * @ingroup client_policies
439  */
440 typedef struct as_policy_query_s {
441 
442  /**
443  * Maximum time in milliseconds to wait for
444  * the operation to complete.
445  *
446  * If 0 (zero), then the value will default to
447  * either as_config.policies.timeout
448  * or Aerospike's recommended default.
449  */
450  uint32_t timeout;
451 
453 
454 /**
455  * Scan Policy
456  *
457  * @ingroup client_policies
458  */
459 typedef struct as_policy_scan_s {
460 
461  /**
462  * Maximum time in milliseconds to wait for the operation to complete.
463  *
464  * If 0 (zero), then the value will default to
465  * either as_config.policies.timeout
466  * or `AS_POLICY_TIMEOUT_DEFAULT`.
467  */
468  uint32_t timeout;
469 
470  /**
471  * Abort the scan if the cluster is not in a
472  * stable state.
473  */
475 
477 
478 /**
479  * Info Policy
480  *
481  * @ingroup client_policies
482  */
483 typedef struct as_policy_info_s {
484 
485  /**
486  * Maximum time in milliseconds to wait for
487  * the operation to complete.
488  *
489  * If 0 (zero), then the value will default to
490  * either as_config.policies.timeout
491  * or `AS_POLICY_TIMEOUT_DEFAULT`.
492  */
493  uint32_t timeout;
494 
495  /**
496  * Send request without any further processing.
497  */
499 
500  /**
501  * Ensure the request is within allowable size limits.
502  */
504 
506 
507 /**
508  * Batch Policy
509  *
510  * @ingroup client_policies
511  */
512 typedef struct as_policy_batch_s {
513 
514  /**
515  * Maximum time in milliseconds to wait for
516  * the operation to complete.
517  *
518  * If 0 (zero), then the value will default to
519  * either as_config.policies.timeout
520  * or `AS_POLICY_TIMEOUT_DEFAULT`.
521  */
522  uint32_t timeout;
523 
525 
526 /**
527  * Struct of all policy values and operation policies.
528  *
529  * This is utilizes by as_config, to define global and default values
530  * for policies.
531  *
532  * @ingroup as_config_t
533  */
534 typedef struct as_policies_s {
535 
536  /***************************************************************************
537  * DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
538  **************************************************************************/
539 
540  /**
541  * Default timeout in milliseconds.
542  *
543  * Will be used if specific policies have a timeout of 0 (zero).
544  *
545  * The default value is `AS_POLICY_TIMEOUT_DEFAULT`.
546  */
547  uint32_t timeout;
548 
549  /**
550  * Specifies the behavior for failed operations.
551  *
552  * The default value is `AS_POLICY_RETRY_DEFAULT`.
553  */
555 
556  /**
557  * Specifies the behavior for the key.
558  *
559  * The default value is `AS_POLICY_KEY_DEFAULT`.
560  */
562 
563  /**
564  * Specifies the behavior for the generation
565  * value.
566  *
567  * The default value is `AS_POLICY_GEN_DEFAULT`.
568  */
570 
571  /**
572  * Specifies the behavior for the existence
573  * of the record.
574  *
575  * The default value is `AS_POLICY_EXISTS_DEFAULT`.
576  */
578 
579  /***************************************************************************
580  * SPECIFIC POLICIES
581  **************************************************************************/
582 
583  /**
584  * The default read policy.
585  */
587 
588  /**
589  * The default write policy.
590  */
592 
593  /**
594  * The default operate policy.
595  */
597 
598  /**
599  * The default remove policy.
600  */
602 
603  /**
604  * The default apply policy.
605  */
607 
608  /**
609  * The default query policy.
610  */
612 
613  /**
614  * The default scan policy.
615  */
617 
618  /**
619  * The default info policy.
620  */
622 
623  /**
624  * The default batch policy.
625  */
627 
628 } as_policies;
629 
630 /******************************************************************************
631  * FUNCTIONS
632  *****************************************************************************/
633 
634 /**
635  * Initialize as_policy_read to default values.
636  *
637  * @param p The policy to initialize
638  * @return The initialized policy.
639  *
640  * @relates as_policy_read
641  */
643 
644 /**
645  * Initialize as_policy_apply to default values.
646  *
647  * @param p The policy to initialize
648  * @return The initialized policy.
649  *
650  * @relates as_policy_apply
651  */
653 
654 /**
655  * Initialize as_policy_write to default values.
656  *
657  * @param p The policy to initialize
658  * @return The initialized policy.
659  *
660  * @relates as_policy_write
661  */
663 
664 /**
665  * Initialize as_policy_operate to default values.
666  *
667  * @param p The policy to initialize
668  * @return The initialized policy.
669  *
670  * @relates as_policy_operate
671  */
673 
674 /**
675  * Initialize as_policy_scan to default values.
676  *
677  * @param p The policy to initialize
678  * @return The initialized policy.
679  *
680  * @relates as_policy_scan
681  */
683 
684 /**
685  * Initialize as_policy_query to default values.
686  *
687  * @param p The policy to initialize
688  * @return The initialized policy.
689  *
690  * @relates as_policy_query
691  */
693 
694 /**
695  * Initialize as_policy_info to default values.
696  *
697  * @param p The policy to initialize
698  * @return The initialized policy.
699  *
700  * @relates as_policy_info
701  */
703 
704 /**
705  * Initialize as_policy_remove to default values.
706  *
707  * @param p The policy to initialize
708  * @return The initialized policy.
709  *
710  * @relates as_policy_remove
711  */
713 
714 /**
715  * Initialize as_policy_batch to default values.
716  *
717  * @param p The policy to initialize
718  * @return The initialized policy.
719  *
720  * @relates as_policy_batch
721  */
723 
724 /**
725  * Initialize as_policies to default values.
726  *
727  * @param p The policies to initialize
728  * @return The initialized policies.
729  *
730  * @relates as_policies
731  */
733 
734 
as_policy_info * as_policy_info_init(as_policy_info *p)
bool fail_on_cluster_change
Definition: as_policy.h:474
as_policy_key
Definition: as_policy.h:188
uint32_t timeout
Definition: as_policy.h:351
as_policy_remove * as_policy_remove_init(as_policy_remove *p)
as_policy_scan scan
Definition: as_policy.h:616
as_policy_key key
Definition: as_policy.h:332
as_policy_gen gen
Definition: as_policy.h:431
as_policy_gen
Definition: as_policy.h:145
as_policy_retry
Definition: as_policy.h:113
as_policy_key key
Definition: as_policy.h:425
bool check_bounds
Definition: as_policy.h:503
as_policy_query * as_policy_query_init(as_policy_query *p)
as_policy_key key
Definition: as_policy.h:385
uint32_t timeout
Definition: as_policy.h:522
as_policy_write * as_policy_write_init(as_policy_write *p)
as_policy_exists
Definition: as_policy.h:238
uint32_t timeout
Definition: as_policy.h:450
as_policy_info info
Definition: as_policy.h:621
as_policy_write write
Definition: as_policy.h:591
as_policy_apply apply
Definition: as_policy.h:606
uint32_t timeout
Definition: as_policy.h:493
uint32_t timeout
Definition: as_policy.h:286
as_policy_apply * as_policy_apply_init(as_policy_apply *p)
uint32_t timeout
Definition: as_policy.h:327
as_policy_query query
Definition: as_policy.h:611
as_policy_operate operate
Definition: as_policy.h:596
as_policy_retry retry
Definition: as_policy.h:554
as_policy_operate * as_policy_operate_init(as_policy_operate *p)
as_policies * as_policies_init(as_policies *p)
as_policy_key key
Definition: as_policy.h:561
as_policy_key key
Definition: as_policy.h:356
uint32_t timeout
Definition: as_policy.h:547
as_policy_gen gen
Definition: as_policy.h:569
as_policy_gen gen
Definition: as_policy.h:391
as_policy_retry retry
Definition: as_policy.h:420
as_policy_batch * as_policy_batch_init(as_policy_batch *p)
as_policy_read * as_policy_read_init(as_policy_read *p)
uint32_t timeout
Definition: as_policy.h:410
as_policy_read read
Definition: as_policy.h:586
as_policy_exists exists
Definition: as_policy.h:577
as_policy_batch batch
Definition: as_policy.h:626
uint32_t timeout
Definition: as_policy.h:468
as_policy_exists exists
Definition: as_policy.h:308
uint32_t timeout
Definition: as_policy.h:375
as_policy_key key
Definition: as_policy.h:296
as_policy_scan * as_policy_scan_init(as_policy_scan *p)
as_policy_gen gen
Definition: as_policy.h:302
as_policy_retry retry
Definition: as_policy.h:291
as_policy_retry retry
Definition: as_policy.h:380
uint16_t generation
Definition: as_policy.h:415