Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
as_policy.h
Go to the documentation of this file.
1
/*
2
* Copyright 2008-2017 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_exists
36
* - as_policy_replica
37
* - as_policy_consistency_level
38
* - as_policy_commit_level
39
*
40
* ## Operation Policies
41
*
42
* The following are the operation policies. Operation policies are groups of
43
* policy values for a type of operation.
44
*
45
* - as_policy_batch
46
* - as_policy_info
47
* - as_policy_operate
48
* - as_policy_read
49
* - as_policy_remove
50
* - as_policy_query
51
* - as_policy_scan
52
* - as_policy_write
53
*/
54
55
#include <stdbool.h>
56
#include <stdint.h>
57
58
#ifdef __cplusplus
59
extern
"C"
{
60
#endif
61
62
/******************************************************************************
63
* MACROS
64
*****************************************************************************/
65
66
/**
67
* Default timeout value
68
*
69
* @ingroup client_policies
70
*/
71
#define AS_POLICY_TIMEOUT_DEFAULT 1000
72
73
/**
74
* Default number of retries when a transaction fails due to a network error.
75
*
76
* @ingroup client_policies
77
*/
78
#define AS_POLICY_RETRY_DEFAULT 1
79
80
/**
81
* Default milliseconds to sleep before a command retry.
82
*
83
* @ingroup client_policies
84
*/
85
#define AS_POLICY_RETRY_SLEEP_DEFAULT 0
86
87
/**
88
* Default value for compression threshold
89
*
90
* @ingroup client_policies
91
*/
92
#define AS_POLICY_COMPRESSION_THRESHOLD_DEFAULT 0
93
94
/**
95
* Default as_policy_gen value
96
*
97
* @ingroup client_policies
98
*/
99
#define AS_POLICY_GEN_DEFAULT AS_POLICY_GEN_IGNORE
100
101
/**
102
* Default as_policy_key value
103
*
104
* @ingroup client_policies
105
*/
106
#define AS_POLICY_KEY_DEFAULT AS_POLICY_KEY_DIGEST
107
108
/**
109
* Default as_policy_exists value
110
*
111
* @ingroup client_policies
112
*/
113
#define AS_POLICY_EXISTS_DEFAULT AS_POLICY_EXISTS_IGNORE
114
115
/**
116
* Default as_policy_replica value
117
*
118
* @ingroup client_policies
119
*/
120
#define AS_POLICY_REPLICA_DEFAULT AS_POLICY_REPLICA_MASTER
121
122
/**
123
* Default as_policy_consistency_level value for read
124
*
125
* @ingroup client_policies
126
*/
127
#define AS_POLICY_CONSISTENCY_LEVEL_DEFAULT AS_POLICY_CONSISTENCY_LEVEL_ONE
128
129
/**
130
* Default as_policy_commit_level value for write
131
*
132
* @ingroup client_policies
133
*/
134
#define AS_POLICY_COMMIT_LEVEL_DEFAULT AS_POLICY_COMMIT_LEVEL_ALL
135
136
/******************************************************************************
137
* TYPES
138
*****************************************************************************/
139
140
/**
141
* Retry Policy
142
*
143
* Specifies the behavior of failed operations.
144
*
145
* @ingroup client_policies
146
*/
147
typedef
enum
as_policy_retry_e {
148
149
/**
150
* Only attempt an operation once.
151
*/
152
AS_POLICY_RETRY_NONE
,
153
154
/**
155
* If an operation fails, attempt the operation
156
* one more time.
157
*/
158
AS_POLICY_RETRY_ONCE
,
159
160
}
as_policy_retry
;
161
162
/**
163
* Generation Policy
164
*
165
* Specifies the behavior of record modifications with regard to the
166
* generation value.
167
*
168
* @ingroup client_policies
169
*/
170
typedef
enum
as_policy_gen_e {
171
172
/**
173
* Write a record, regardless of generation.
174
*/
175
AS_POLICY_GEN_IGNORE
,
176
177
/**
178
* Write a record, ONLY if generations are equal
179
*/
180
AS_POLICY_GEN_EQ
,
181
182
/**
183
* Write a record, ONLY if local generation is
184
* greater-than remote generation
185
*/
186
AS_POLICY_GEN_GT
187
188
}
as_policy_gen
;
189
190
/**
191
* Key Policy
192
*
193
* Specifies the behavior for whether keys or digests
194
* should be sent to the cluster.
195
*
196
* @ingroup client_policies
197
*/
198
typedef
enum
as_policy_key_e {
199
200
/**
201
* Send the digest value of the key.
202
*
203
* This is the recommended mode of operation. This calculates the digest
204
* and send the digest to the server. The digest is only calculated on
205
* the client, and not on the server.
206
*/
207
AS_POLICY_KEY_DIGEST
,
208
209
/**
210
* Send the key, in addition to the digest value.
211
*
212
* If you want keys to be returned when scanning or querying, the keys must
213
* be stored on the server. This policy causes a write operation to store
214
* the key. Once a key is stored, the server will keep it - there is no
215
* need to use this policy on subsequent updates of the record.
216
*
217
* If this policy is used on read or delete operations, or on subsequent
218
* updates of a record with a stored key, the key sent will be compared
219
* with the key stored on the server. A mismatch will cause
220
* AEROSPIKE_ERR_RECORD_KEY_MISMATCH to be returned.
221
*/
222
AS_POLICY_KEY_SEND
,
223
224
}
as_policy_key
;
225
226
/**
227
* Existence Policy
228
*
229
* Specifies the behavior for writing the record
230
* depending whether or not it exists.
231
*
232
* @ingroup client_policies
233
*/
234
typedef
enum
as_policy_exists_e {
235
236
/**
237
* Write the record, regardless of existence. (i.e. create or update.)
238
*/
239
AS_POLICY_EXISTS_IGNORE
,
240
241
/**
242
* Create a record, ONLY if it doesn't exist.
243
*/
244
AS_POLICY_EXISTS_CREATE
,
245
246
/**
247
* Update a record, ONLY if it exists.
248
*/
249
AS_POLICY_EXISTS_UPDATE
,
250
251
/**
252
* Completely replace a record, ONLY if it exists.
253
*/
254
AS_POLICY_EXISTS_REPLACE
,
255
256
/**
257
* Completely replace a record if it exists, otherwise create it.
258
*/
259
AS_POLICY_EXISTS_CREATE_OR_REPLACE
260
261
}
as_policy_exists
;
262
263
/**
264
* Replica Policy
265
*
266
* Specifies which partition replica to read from.
267
*
268
* @ingroup client_policies
269
*/
270
typedef
enum
as_policy_replica_e {
271
272
/**
273
* Read from the partition master replica node.
274
*/
275
AS_POLICY_REPLICA_MASTER
,
276
277
/**
278
* Distribute reads across nodes containing key's master and replicated partition
279
* in round-robin fashion. Currently restricted to master and one prole.
280
*/
281
AS_POLICY_REPLICA_ANY
,
282
283
/**
284
* Always try node containing master partition first. If connection fails and
285
* `retry_on_timeout` is true, try node containing prole partition.
286
* Currently restricted to master and one prole.
287
*/
288
AS_POLICY_REPLICA_SEQUENCE
289
290
}
as_policy_replica
;
291
292
/**
293
* Consistency Level
294
*
295
* Specifies the number of replicas to be consulted
296
* in a read operation to provide the desired
297
* consistency guarantee.
298
*
299
* @ingroup client_policies
300
*/
301
typedef
enum
as_policy_consistency_level_e {
302
303
/**
304
* Involve a single replica in the operation.
305
*/
306
AS_POLICY_CONSISTENCY_LEVEL_ONE
,
307
308
/**
309
* Involve all replicas in the operation.
310
*/
311
AS_POLICY_CONSISTENCY_LEVEL_ALL
,
312
313
}
as_policy_consistency_level
;
314
315
/**
316
* Commit Level
317
*
318
* Specifies the number of replicas required to be successfully
319
* committed before returning success in a write operation
320
* to provide the desired consistency guarantee.
321
*
322
* @ingroup client_policies
323
*/
324
typedef
enum
as_policy_commit_level_e {
325
326
/**
327
* Return succcess only after successfully committing all replicas.
328
*/
329
AS_POLICY_COMMIT_LEVEL_ALL
,
330
331
/**
332
* Return succcess after successfully committing the master replica.
333
*/
334
AS_POLICY_COMMIT_LEVEL_MASTER
,
335
336
}
as_policy_commit_level
;
337
338
/**
339
* Write Policy
340
*
341
* @ingroup client_policies
342
*/
343
typedef
struct
as_policy_write_s {
344
345
/**
346
* Maximum time in milliseconds to wait for the operation to complete.
347
*/
348
uint32_t
timeout
;
349
350
/**
351
* Maximum number of retries when a transaction fails due to a network error.
352
* Used by synchronous commands only.
353
* Default: 1
354
*/
355
uint32_t
retry
;
356
357
/**
358
* Milliseconds to sleep between retries.
359
* Used by synchronous commands only.
360
* Default: 0 (do not sleep)
361
*/
362
uint32_t
sleep_between_retries
;
363
364
/**
365
* Minimum record size beyond which it is compressed and sent to the server.
366
*/
367
uint32_t
compression_threshold
;
368
369
/**
370
* Specifies the behavior for the key.
371
*/
372
as_policy_key
key
;
373
374
/**
375
* Specifies the behavior for the generation
376
* value.
377
*/
378
as_policy_gen
gen
;
379
380
/**
381
* Specifies the behavior for the existence
382
* of the record.
383
*/
384
as_policy_exists
exists
;
385
386
/**
387
* Specifies the number of replicas required
388
* to be committed successfully when writing
389
* before returning transaction succeeded.
390
*/
391
as_policy_commit_level
commit_level
;
392
393
/**
394
* Should the client retry a command if the timeout is reached.
395
* Used by synchronous commands only.
396
* <p>
397
* Values:
398
* <ul>
399
* <li>
400
* false: Return error when the timeout has been reached. Note that retries can still occur if
401
* a command fails on a network error before the timeout has been reached.
402
* </li>
403
* <li>
404
* true: Retry command with same timeout when the timeout has been reached. The maximum number
405
* of retries is defined by `retry`.
406
* </li>
407
* </ul>
408
* Default: false
409
*/
410
bool
retry_on_timeout
;
411
412
/**
413
* If the transaction results in a record deletion, leave a tombstone for the record.
414
* This prevents deleted records from reappearing after node failures.
415
* Valid for Aerospike Server Enterprise Edition only.
416
*
417
* Default: false (do not tombstone deleted records).
418
*/
419
bool
durable_delete
;
420
421
}
as_policy_write
;
422
423
/**
424
* Read Policy
425
*
426
* @ingroup client_policies
427
*/
428
typedef
struct
as_policy_read_s {
429
430
/**
431
* Maximum time in milliseconds to wait for the operation to complete.
432
*/
433
uint32_t
timeout
;
434
435
/**
436
* Maximum number of retries when a transaction fails due to a network error.
437
* Used by synchronous commands only.
438
* Default: 1
439
*/
440
uint32_t
retry
;
441
442
/**
443
* Milliseconds to sleep between retries.
444
* Used by synchronous commands only.
445
* Default: 0 (do not sleep)
446
*/
447
uint32_t
sleep_between_retries
;
448
449
/**
450
* Specifies the behavior for the key.
451
*/
452
as_policy_key
key
;
453
454
/**
455
* Specifies the replica to be consulted for the read.
456
*/
457
as_policy_replica
replica
;
458
459
/**
460
* Specifies the number of replicas consulted
461
* when reading for the desired consistency guarantee.
462
*/
463
as_policy_consistency_level
consistency_level
;
464
465
/**
466
* Should the client retry a command if the timeout is reached.
467
* Used by synchronous commands only.
468
* <p>
469
* Values:
470
* <ul>
471
* <li>
472
* false: Return error when the timeout has been reached. Note that retries can still occur if
473
* a command fails on a network error before the timeout has been reached.
474
* </li>
475
* <li>
476
* true: Retry command with same timeout when the timeout has been reached. The maximum number
477
* of retries is defined by `retry`.
478
* </li>
479
* </ul>
480
* Default: false
481
*/
482
bool
retry_on_timeout
;
483
484
/**
485
* Should raw bytes representing a list or map be deserialized to as_list or as_map.
486
* Set to false for backup programs that just need access to raw bytes.
487
* Default: true
488
*/
489
bool
deserialize
;
490
491
}
as_policy_read
;
492
493
/**
494
* Key Apply Policy
495
*
496
* @ingroup client_policies
497
*/
498
typedef
struct
as_policy_apply_s {
499
500
/**
501
* Maximum time in milliseconds to wait for the operation to complete.
502
*/
503
uint32_t
timeout
;
504
505
/**
506
* Maximum number of retries when a transaction fails due to a network error.
507
* Used by synchronous commands only.
508
* Default: 1
509
*/
510
uint32_t
retry
;
511
512
/**
513
* Milliseconds to sleep between retries.
514
* Used by synchronous commands only.
515
* Default: 0 (do not sleep)
516
*/
517
uint32_t
sleep_between_retries
;
518
519
/**
520
* Specifies the behavior for the key.
521
*/
522
as_policy_key
key
;
523
524
/**
525
* Specifies the number of replicas required
526
* to be committed successfully when writing
527
* before returning transaction succeeded.
528
*/
529
as_policy_commit_level
commit_level
;
530
531
/**
532
* The time-to-live (expiration) of the record in seconds.
533
* There are also special values that can be set in the record TTL:
534
* (*) ZERO (defined as AS_RECORD_DEFAULT_TTL), which means that the
535
* record will adopt the default TTL value from the namespace.
536
* (*) 0xFFFFFFFF (also, -1 in a signed 32 bit int)
537
* (defined as AS_RECORD_NO_EXPIRE_TTL), which means that the record
538
* will get an internal "void_time" of zero, and thus will never expire.
539
* (*) 0xFFFFFFFE (also, -2 in a signed 32 bit int)
540
* (defined as AS_RECORD_NO_CHANGE_TTL), which means that the record
541
* ttl will not change when the record is updated.
542
*
543
* Note that the TTL value will be employed ONLY on write/update calls.
544
*/
545
uint32_t
ttl
;
546
547
/**
548
* Should the client retry a command if the timeout is reached.
549
* Used by synchronous commands only.
550
* <p>
551
* Values:
552
* <ul>
553
* <li>
554
* false: Return error when the timeout has been reached. Note that retries can still occur if
555
* a command fails on a network error before the timeout has been reached.
556
* </li>
557
* <li>
558
* true: Retry command with same timeout when the timeout has been reached. The maximum number
559
* of retries is defined by `retry`.
560
* </li>
561
* </ul>
562
* Default: false
563
*/
564
bool
retry_on_timeout
;
565
566
/**
567
* If the transaction results in a record deletion, leave a tombstone for the record.
568
* This prevents deleted records from reappearing after node failures.
569
* Valid for Aerospike Server Enterprise Edition only.
570
*
571
* Default: false (do not tombstone deleted records).
572
*/
573
bool
durable_delete
;
574
575
}
as_policy_apply
;
576
577
/**
578
* Operate Policy
579
*
580
* @ingroup client_policies
581
*/
582
typedef
struct
as_policy_operate_s {
583
584
/**
585
* Maximum time in milliseconds to wait for the operation to complete.
586
*/
587
uint32_t
timeout
;
588
589
/**
590
* Maximum number of retries when a transaction fails due to a network error.
591
* Used by synchronous commands only.
592
* Default: 1
593
*/
594
uint32_t
retry
;
595
596
/**
597
* Milliseconds to sleep between retries.
598
* Used by synchronous commands only.
599
* Default: 0 (do not sleep)
600
*/
601
uint32_t
sleep_between_retries
;
602
603
/**
604
* Specifies the behavior for the key.
605
*/
606
as_policy_key
key
;
607
608
/**
609
* Specifies the behavior for the generation
610
* value.
611
*/
612
as_policy_gen
gen
;
613
614
/**
615
* Specifies the replica to be consulted for the read.
616
*/
617
as_policy_replica
replica
;
618
619
/**
620
* Specifies the number of replicas consulted
621
* when reading for the desired consistency guarantee.
622
*/
623
as_policy_consistency_level
consistency_level
;
624
625
/**
626
* Specifies the number of replicas required
627
* to be committed successfully when writing
628
* before returning transaction succeeded.
629
*/
630
as_policy_commit_level
commit_level
;
631
632
/**
633
* Should the client retry a command if the timeout is reached.
634
* Used by synchronous commands only.
635
* <p>
636
* Values:
637
* <ul>
638
* <li>
639
* false: Return error when the timeout has been reached. Note that retries can still occur if
640
* a command fails on a network error before the timeout has been reached.
641
* </li>
642
* <li>
643
* true: Retry command with same timeout when the timeout has been reached. The maximum number
644
* of retries is defined by `retry`.
645
* </li>
646
* </ul>
647
* Default: false
648
*/
649
bool
retry_on_timeout
;
650
651
/**
652
* Should raw bytes representing a list or map be deserialized to as_list or as_map.
653
* Set to false for backup programs that just need access to raw bytes.
654
* Default: true
655
*/
656
bool
deserialize
;
657
658
/**
659
* If the transaction results in a record deletion, leave a tombstone for the record.
660
* This prevents deleted records from reappearing after node failures.
661
* Valid for Aerospike Server Enterprise Edition only.
662
*
663
* Default: false (do not tombstone deleted records).
664
*/
665
bool
durable_delete
;
666
667
}
as_policy_operate
;
668
669
/**
670
* Remove Policy
671
*
672
* @ingroup client_policies
673
*/
674
typedef
struct
as_policy_remove_s {
675
676
/**
677
* Maximum time in milliseconds to wait for the operation to complete.
678
*/
679
uint32_t
timeout
;
680
681
/**
682
* Maximum number of retries when a transaction fails due to a network error.
683
* Used by synchronous commands only.
684
* Default: 1
685
*/
686
uint32_t
retry
;
687
688
/**
689
* Milliseconds to sleep between retries.
690
* Used by synchronous commands only.
691
* Default: 0 (do not sleep)
692
*/
693
uint32_t
sleep_between_retries
;
694
695
/**
696
* Specifies the behavior for the key.
697
*/
698
as_policy_key
key
;
699
700
/**
701
* Specifies the behavior for the generation
702
* value.
703
*/
704
as_policy_gen
gen
;
705
706
/**
707
* Specifies the number of replicas required
708
* to be committed successfully when writing
709
* before returning transaction succeeded.
710
*/
711
as_policy_commit_level
commit_level
;
712
713
/**
714
* The generation of the record.
715
*/
716
uint16_t
generation
;
717
718
/**
719
* Should the client retry a command if the timeout is reached.
720
* Used by synchronous commands only.
721
* <p>
722
* Values:
723
* <ul>
724
* <li>
725
* false: Return error when the timeout has been reached. Note that retries can still occur if
726
* a command fails on a network error before the timeout has been reached.
727
* </li>
728
* <li>
729
* true: Retry command with same timeout when the timeout has been reached. The maximum number
730
* of retries is defined by `retry`.
731
* </li>
732
* </ul>
733
* Default: false
734
*/
735
bool
retry_on_timeout
;
736
737
/**
738
* If the transaction results in a record deletion, leave a tombstone for the record.
739
* This prevents deleted records from reappearing after node failures.
740
* Valid for Aerospike Server Enterprise Edition only.
741
*
742
* Default: false (do not tombstone deleted records).
743
*/
744
bool
durable_delete
;
745
746
}
as_policy_remove
;
747
748
/**
749
* Query Policy
750
*
751
* @ingroup client_policies
752
*/
753
typedef
struct
as_policy_query_s {
754
755
/**
756
* Maximum time in milliseconds to wait for the operation to complete.
757
* The default (0) means do not apply a total timeout.
758
*/
759
uint32_t
timeout
;
760
761
/**
762
* Maximum socket idle time in milliseconds when processing a database command.
763
* Zero means do not apply a socket idle timeout.
764
*
765
* Default: 10000 ms
766
*/
767
uint32_t
socket_timeout
;
768
769
/**
770
* Should raw bytes representing a list or map be deserialized to as_list or as_map.
771
* Set to false for backup programs that just need access to raw bytes.
772
* Default: true
773
*/
774
bool
deserialize
;
775
776
}
as_policy_query
;
777
778
/**
779
* Scan Policy
780
*
781
* @ingroup client_policies
782
*/
783
typedef
struct
as_policy_scan_s {
784
785
/**
786
* Maximum time in milliseconds to wait for the operation to complete.
787
* The default (0) means do not apply a total timeout.
788
*/
789
uint32_t
timeout
;
790
791
/**
792
* Maximum socket idle time in milliseconds when processing a database command.
793
* Zero means do not apply a socket idle timeout.
794
*
795
* This scan socket timeout is also applied on server side as well.
796
*
797
* Default: 10000 ms
798
*/
799
uint32_t
socket_timeout
;
800
801
/**
802
* Abort the scan if the cluster is not in a stable state.
803
*/
804
bool
fail_on_cluster_change
;
805
806
/**
807
* If the scan runs a UDF which results in a record deletion, leave a tombstone for the record.
808
* This prevents deleted records from reappearing after node failures.
809
* Valid for Aerospike Server Enterprise Edition only.
810
*
811
* Default: false (do not tombstone deleted records).
812
*/
813
bool
durable_delete
;
814
815
}
as_policy_scan
;
816
817
/**
818
* Info Policy
819
*
820
* @ingroup client_policies
821
*/
822
typedef
struct
as_policy_info_s {
823
824
/**
825
* Maximum time in milliseconds to wait for
826
* the operation to complete.
827
*/
828
uint32_t
timeout
;
829
830
/**
831
* Send request without any further processing.
832
*/
833
bool
send_as_is
;
834
835
/**
836
* Ensure the request is within allowable size limits.
837
*/
838
bool
check_bounds
;
839
840
}
as_policy_info
;
841
842
/**
843
* Batch Policy
844
*
845
* @ingroup client_policies
846
*/
847
typedef
struct
as_policy_batch_s {
848
849
/**
850
* Maximum time in milliseconds to wait for the operation to complete.
851
*/
852
uint32_t
timeout
;
853
854
/**
855
* Maximum number of retries when a transaction fails due to a network error.
856
* Used by synchronous commands only.
857
* Default: 1
858
*/
859
uint32_t
retry
;
860
861
/**
862
* Milliseconds to sleep between retries.
863
* Used by synchronous commands only.
864
* Default: 0 (do not sleep)
865
*/
866
uint32_t
sleep_between_retries
;
867
868
/**
869
* Specifies the number of replicas consulted
870
* when reading for the desired consistency guarantee.
871
*/
872
as_policy_consistency_level
consistency_level
;
873
874
/**
875
* Should the client retry a command if the timeout is reached.
876
* Used by synchronous commands only.
877
* <p>
878
* Values:
879
* <ul>
880
* <li>
881
* false: Return error when the timeout has been reached. Note that retries can still occur if
882
* a command fails on a network error before the timeout has been reached.
883
* </li>
884
* <li>
885
* true: Retry command with same timeout when the timeout has been reached. The maximum number
886
* of retries is defined by `retry`.
887
* </li>
888
* </ul>
889
* Default: false
890
*/
891
bool
retry_on_timeout
;
892
893
/**
894
* Determine if batch commands to each server are run in parallel threads.
895
* <p>
896
* Values:
897
* <ul>
898
* <li>
899
* false: Issue batch commands sequentially. This mode has a performance advantage for small
900
* to medium sized batch sizes because commands can be issued in the main transaction thread.
901
* This is the default.
902
* </li>
903
* <li>
904
* true: Issue batch commands in parallel threads. This mode has a performance
905
* advantage for large batch sizes because each node can process the command immediately.
906
* The downside is extra threads will need to be created (or taken from
907
* a thread pool).
908
* </li>
909
* </ul>
910
*/
911
bool
concurrent
;
912
913
/**
914
* Use old batch direct protocol where batch reads are handled by direct low-level batch server
915
* database routines. The batch direct protocol can be faster when there is a single namespace,
916
* but there is one important drawback. The batch direct protocol will not proxy to a different
917
* server node when the mapped node has migrated a record to another node (resulting in not
918
* found record).
919
* <p>
920
* This can happen after a node has been added/removed from the cluster and there is a lag
921
* between records being migrated and client partition map update (once per second).
922
* <p>
923
* The new batch index protocol will perform this record proxy when necessary.
924
* Default: false (use new batch index protocol if server supports it)
925
*/
926
bool
use_batch_direct
;
927
928
/**
929
* Allow batch to be processed immediately in the server's receiving thread when the server
930
* deems it to be appropriate. If false, the batch will always be processed in separate
931
* transaction threads. This field is only relevant for the new batch index protocol.
932
* <p>
933
* For batch exists or batch reads of smaller sized records (<= 1K per record), inline
934
* processing will be significantly faster on "in memory" namespaces. The server disables
935
* inline processing on disk based namespaces regardless of this policy field.
936
* <p>
937
* Inline processing can introduce the possibility of unfairness because the server
938
* can process the entire batch before moving onto the next command.
939
* Default: true
940
*/
941
bool
allow_inline
;
942
943
/**
944
* Send set name field to server for every key in the batch for batch index protocol.
945
* This is only necessary when authentication is enabled and security roles are defined
946
* on a per set basis.
947
* Default: false
948
*/
949
bool
send_set_name
;
950
951
/**
952
* Should raw bytes be deserialized to as_list or as_map. Set to false for backup programs that
953
* just need access to raw bytes.
954
* Default: true
955
*/
956
bool
deserialize
;
957
958
}
as_policy_batch
;
959
960
/**
961
* Administration Policy
962
*
963
* @ingroup client_policies
964
*/
965
typedef
struct
as_policy_admin_s {
966
967
/**
968
* Maximum time in milliseconds to wait for
969
* the operation to complete.
970
*/
971
uint32_t
timeout
;
972
973
}
as_policy_admin
;
974
975
/**
976
* Struct of all policy values and operation policies.
977
*
978
* This is utilizes by as_config, to define global and default values
979
* for policies.
980
*
981
* @ingroup as_config_t
982
*/
983
typedef
struct
as_policies_s {
984
985
/***************************************************************************
986
* DEFAULT VALUES, IF SPECIFIC POLICY IS UNDEFINED
987
**************************************************************************/
988
989
/**
990
* Default timeout in milliseconds.
991
*
992
* Default: `AS_POLICY_TIMEOUT_DEFAULT`
993
*/
994
uint32_t
timeout
;
995
996
/**
997
* Default maximum number of retries when a transaction fails due to a network error.
998
*
999
* Default: `AS_POLICY_RETRY_DEFAULT`
1000
*/
1001
uint32_t
retry
;
1002
1003
/**
1004
* Default milliseconds to sleep between retries.
1005
*
1006
* Default: `AS_POLICY_RETRY_SLEEP_DEFAULT`
1007
*/
1008
uint32_t
sleep_between_retries
;
1009
1010
/**
1011
* Specifies the behavior for the key.
1012
*
1013
* Default: `AS_POLICY_KEY_DEFAULT`
1014
*/
1015
as_policy_key
key
;
1016
1017
/**
1018
* Specifies the behavior for the generation
1019
* value.
1020
*
1021
* Default: `AS_POLICY_GEN_DEFAULT`
1022
*/
1023
as_policy_gen
gen
;
1024
1025
/**
1026
* Specifies the behavior for the existence
1027
* of the record.
1028
*
1029
* Default: `AS_POLICY_EXISTS_DEFAULT`
1030
*/
1031
as_policy_exists
exists
;
1032
1033
/**
1034
* Specifies which replica to read.
1035
*
1036
* Default: `AS_POLICY_REPLICA_MASTER`
1037
*/
1038
as_policy_replica
replica
;
1039
1040
/**
1041
* Specifies the consistency level for reading.
1042
*
1043
* Default: `AS_POLICY_CONSISTENCY_LEVEL_ONE`
1044
*/
1045
as_policy_consistency_level
consistency_level
;
1046
1047
/**
1048
* Specifies the commit level for writing.
1049
*
1050
* Default: `AS_POLICY_COMMIT_LEVEL_ALL`
1051
*/
1052
as_policy_commit_level
commit_level
;
1053
1054
/***************************************************************************
1055
* SPECIFIC POLICIES
1056
**************************************************************************/
1057
1058
/**
1059
* The default read policy.
1060
*/
1061
as_policy_read
read
;
1062
1063
/**
1064
* The default write policy.
1065
*/
1066
as_policy_write
write
;
1067
1068
/**
1069
* The default operate policy.
1070
*/
1071
as_policy_operate
operate
;
1072
1073
/**
1074
* The default remove policy.
1075
*/
1076
as_policy_remove
remove
;
1077
1078
/**
1079
* The default apply policy.
1080
*/
1081
as_policy_apply
apply
;
1082
1083
/**
1084
* The default query policy.
1085
*/
1086
as_policy_query
query
;
1087
1088
/**
1089
* The default scan policy.
1090
*/
1091
as_policy_scan
scan
;
1092
1093
/**
1094
* The default info policy.
1095
*/
1096
as_policy_info
info
;
1097
1098
/**
1099
* The default batch policy.
1100
*/
1101
as_policy_batch
batch
;
1102
1103
/**
1104
* The default administration policy.
1105
*/
1106
as_policy_admin
admin
;
1107
1108
}
as_policies
;
1109
1110
/******************************************************************************
1111
* FUNCTIONS
1112
*****************************************************************************/
1113
1114
/**
1115
* Initialize as_policy_read to default values.
1116
*
1117
* @param p The policy to initialize.
1118
* @return The initialized policy.
1119
*
1120
* @relates as_policy_read
1121
*/
1122
static
inline
as_policy_read
*
1123
as_policy_read_init
(
as_policy_read
* p)
1124
{
1125
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1126
p->
retry
=
AS_POLICY_RETRY_DEFAULT
;
1127
p->
sleep_between_retries
=
AS_POLICY_RETRY_SLEEP_DEFAULT
;
1128
p->
key
=
AS_POLICY_KEY_DEFAULT
;
1129
p->
replica
=
AS_POLICY_REPLICA_DEFAULT
;
1130
p->
consistency_level
=
AS_POLICY_CONSISTENCY_LEVEL_DEFAULT
;
1131
p->
retry_on_timeout
=
false
;
1132
p->
deserialize
=
true
;
1133
return
p;
1134
}
1135
1136
/**
1137
* Copy as_policy_read values.
1138
*
1139
* @param src The source policy.
1140
* @param trg The target policy.
1141
*
1142
* @relates as_policy_read
1143
*/
1144
static
inline
void
1145
as_policy_read_copy
(
as_policy_read
* src,
as_policy_read
* trg)
1146
{
1147
*trg = *src;
1148
}
1149
1150
/**
1151
* Initialize as_policy_write to default values.
1152
*
1153
* @param p The policy to initialize.
1154
* @return The initialized policy.
1155
*
1156
* @relates as_policy_write
1157
*/
1158
static
inline
as_policy_write
*
1159
as_policy_write_init
(
as_policy_write
* p)
1160
{
1161
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1162
p->
retry
=
AS_POLICY_RETRY_DEFAULT
;
1163
p->
sleep_between_retries
=
AS_POLICY_RETRY_SLEEP_DEFAULT
;
1164
p->
compression_threshold
=
AS_POLICY_COMPRESSION_THRESHOLD_DEFAULT
;
1165
p->
key
=
AS_POLICY_KEY_DEFAULT
;
1166
p->
gen
=
AS_POLICY_GEN_DEFAULT
;
1167
p->
exists
=
AS_POLICY_EXISTS_DEFAULT
;
1168
p->
commit_level
=
AS_POLICY_COMMIT_LEVEL_DEFAULT
;
1169
p->
retry_on_timeout
=
false
;
1170
p->
durable_delete
=
false
;
1171
return
p;
1172
}
1173
1174
/**
1175
* Copy as_policy_write values.
1176
*
1177
* @param src The source policy.
1178
* @param trg The target policy.
1179
*
1180
* @relates as_policy_write
1181
*/
1182
static
inline
void
1183
as_policy_write_copy
(
as_policy_write
* src,
as_policy_write
* trg)
1184
{
1185
*trg = *src;
1186
}
1187
1188
/**
1189
* Initialize as_policy_operate to default values.
1190
*
1191
* @param p The policy to initialize.
1192
* @return The initialized policy.
1193
*
1194
* @relates as_policy_operate
1195
*/
1196
static
inline
as_policy_operate
*
1197
as_policy_operate_init
(
as_policy_operate
* p)
1198
{
1199
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1200
p->
retry
=
AS_POLICY_RETRY_DEFAULT
;
1201
p->
sleep_between_retries
=
AS_POLICY_RETRY_SLEEP_DEFAULT
;
1202
p->
key
=
AS_POLICY_KEY_DEFAULT
;
1203
p->
gen
=
AS_POLICY_GEN_DEFAULT
;
1204
p->
replica
=
AS_POLICY_REPLICA_DEFAULT
;
1205
p->
consistency_level
=
AS_POLICY_CONSISTENCY_LEVEL_DEFAULT
;
1206
p->
commit_level
=
AS_POLICY_COMMIT_LEVEL_DEFAULT
;
1207
p->
retry_on_timeout
=
false
;
1208
p->
deserialize
=
true
;
1209
p->
durable_delete
=
false
;
1210
return
p;
1211
}
1212
1213
/**
1214
* Copy as_policy_operate values.
1215
*
1216
* @param src The source policy.
1217
* @param trg The target policy.
1218
*
1219
* @relates as_policy_operate
1220
*/
1221
static
inline
void
1222
as_policy_operate_copy
(
as_policy_operate
* src,
as_policy_operate
* trg)
1223
{
1224
*trg = *src;
1225
}
1226
1227
/**
1228
* Initialize as_policy_remove to default values.
1229
*
1230
* @param p The policy to initialize.
1231
* @return The initialized policy.
1232
*
1233
* @relates as_policy_remove
1234
*/
1235
static
inline
as_policy_remove
*
1236
as_policy_remove_init
(
as_policy_remove
* p)
1237
{
1238
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1239
p->
retry
=
AS_POLICY_RETRY_DEFAULT
;
1240
p->
sleep_between_retries
=
AS_POLICY_RETRY_SLEEP_DEFAULT
;
1241
p->
key
=
AS_POLICY_KEY_DEFAULT
;
1242
p->
gen
=
AS_POLICY_GEN_DEFAULT
;
1243
p->
commit_level
=
AS_POLICY_COMMIT_LEVEL_DEFAULT
;
1244
p->
generation
= 0;
1245
p->
retry_on_timeout
=
false
;
1246
p->
durable_delete
=
false
;
1247
return
p;
1248
}
1249
1250
/**
1251
* Copy as_policy_remove values.
1252
*
1253
* @param src The source policy.
1254
* @param trg The target policy.
1255
*
1256
* @relates as_policy_remove
1257
*/
1258
static
inline
void
1259
as_policy_remove_copy
(
as_policy_remove
* src,
as_policy_remove
* trg)
1260
{
1261
*trg = *src;
1262
}
1263
1264
/**
1265
* Initialize as_policy_apply to default values.
1266
*
1267
* @param p The policy to initialize.
1268
* @return The initialized policy.
1269
*
1270
* @relates as_policy_apply
1271
*/
1272
static
inline
as_policy_apply
*
1273
as_policy_apply_init
(
as_policy_apply
* p)
1274
{
1275
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1276
p->
retry
=
AS_POLICY_RETRY_DEFAULT
;
1277
p->
sleep_between_retries
=
AS_POLICY_RETRY_SLEEP_DEFAULT
;
1278
p->
key
=
AS_POLICY_KEY_DEFAULT
;
1279
p->
commit_level
=
AS_POLICY_COMMIT_LEVEL_DEFAULT
;
1280
p->
ttl
= 0;
// AS_RECORD_DEFAULT_TTL
1281
p->
retry_on_timeout
=
false
;
1282
p->
durable_delete
=
false
;
1283
return
p;
1284
}
1285
1286
/**
1287
* Copy as_policy_apply values.
1288
*
1289
* @param src The source policy.
1290
* @param trg The target policy.
1291
*
1292
* @relates as_policy_apply
1293
*/
1294
static
inline
void
1295
as_policy_apply_copy
(
as_policy_apply
* src,
as_policy_apply
* trg)
1296
{
1297
*trg = *src;
1298
}
1299
1300
/**
1301
* Initialize as_policy_info to default values.
1302
*
1303
* @param p The policy to initialize.
1304
* @return The initialized policy.
1305
*
1306
* @relates as_policy_info
1307
*/
1308
static
inline
as_policy_info
*
1309
as_policy_info_init
(
as_policy_info
* p)
1310
{
1311
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1312
p->
send_as_is
=
true
;
1313
p->
check_bounds
=
true
;
1314
return
p;
1315
}
1316
1317
/**
1318
* Copy as_policy_info values.
1319
*
1320
* @param src The source policy.
1321
* @param trg The target policy.
1322
*
1323
* @relates as_policy_info
1324
*/
1325
static
inline
void
1326
as_policy_info_copy
(
as_policy_info
* src,
as_policy_info
* trg)
1327
{
1328
*trg = *src;
1329
}
1330
1331
/**
1332
* Initialize as_policy_batch to default values.
1333
*
1334
* @param p The policy to initialize.
1335
* @return The initialized policy.
1336
*
1337
* @relates as_policy_batch
1338
*/
1339
static
inline
as_policy_batch
*
1340
as_policy_batch_init
(
as_policy_batch
* p)
1341
{
1342
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1343
p->
retry
=
AS_POLICY_RETRY_DEFAULT
;
1344
p->
sleep_between_retries
=
AS_POLICY_RETRY_SLEEP_DEFAULT
;
1345
p->
consistency_level
=
AS_POLICY_CONSISTENCY_LEVEL_ONE
;
1346
p->
retry_on_timeout
=
false
;
1347
p->
concurrent
=
false
;
1348
p->
use_batch_direct
=
false
;
1349
p->
allow_inline
=
true
;
1350
p->
send_set_name
=
false
;
1351
p->
deserialize
=
true
;
1352
return
p;
1353
}
1354
1355
/**
1356
* Copy as_policy_batch values.
1357
*
1358
* @param src The source policy.
1359
* @param trg The target policy.
1360
*
1361
* @relates as_policy_batch
1362
*/
1363
static
inline
void
1364
as_policy_batch_copy
(
as_policy_batch
* src,
as_policy_batch
* trg)
1365
{
1366
*trg = *src;
1367
}
1368
1369
/**
1370
* Initialize as_policy_admin to default values.
1371
*
1372
* @param p The policy to initialize.
1373
* @return The initialized policy.
1374
*
1375
* @relates as_policy_admin
1376
*/
1377
static
inline
as_policy_admin
*
1378
as_policy_admin_init
(
as_policy_admin
* p)
1379
{
1380
p->
timeout
=
AS_POLICY_TIMEOUT_DEFAULT
;
1381
return
p;
1382
}
1383
1384
/**
1385
* Copy as_policy_admin values.
1386
*
1387
* @param src The source policy.
1388
* @param trg The target policy.
1389
*
1390
* @relates as_policy_admin
1391
*/
1392
static
inline
void
1393
as_policy_admin_copy
(
as_policy_admin
* src,
as_policy_admin
* trg)
1394
{
1395
*trg = *src;
1396
}
1397
1398
/**
1399
* Initialize as_policy_scan to default values.
1400
*
1401
* @param p The policy to initialize.
1402
* @return The initialized policy.
1403
*
1404
* @relates as_policy_scan
1405
*/
1406
static
inline
as_policy_scan
*
1407
as_policy_scan_init
(
as_policy_scan
* p)
1408
{
1409
p->
timeout
= 0;
1410
p->
socket_timeout
= 10000;
1411
p->
fail_on_cluster_change
=
false
;
1412
p->
durable_delete
=
false
;
1413
return
p;
1414
}
1415
1416
/**
1417
* Copy as_policy_scan values.
1418
*
1419
* @param src The source policy.
1420
* @param trg The target policy.
1421
*
1422
* @relates as_policy_scan
1423
*/
1424
static
inline
void
1425
as_policy_scan_copy
(
as_policy_scan
* src,
as_policy_scan
* trg)
1426
{
1427
*trg = *src;
1428
}
1429
1430
/**
1431
* Initialize as_policy_query to default values.
1432
*
1433
* @param p The policy to initialize.
1434
* @return The initialized policy.
1435
*
1436
* @relates as_policy_query
1437
*/
1438
static
inline
as_policy_query
*
1439
as_policy_query_init
(
as_policy_query
* p)
1440
{
1441
p->
timeout
= 0;
1442
p->
socket_timeout
= 10000;
1443
p->
deserialize
=
true
;
1444
return
p;
1445
}
1446
1447
/**
1448
* Copy as_policy_query values.
1449
*
1450
* @param src The source policy.
1451
* @param trg The target policy.
1452
*
1453
* @relates as_policy_query
1454
*/
1455
static
inline
void
1456
as_policy_query_copy
(
as_policy_query
* src,
as_policy_query
* trg)
1457
{
1458
*trg = *src;
1459
}
1460
1461
/**
1462
* Initialize as_policies to undefined values.
1463
* as_policies_resolve() will later be called resolve undefined values to global defaults.
1464
*
1465
* @param p The policies to undefine
1466
* @return The undefined policies.
1467
*
1468
* @relates as_policies
1469
*/
1470
as_policies
*
1471
as_policies_init
(
as_policies
* p);
1472
1473
/**
1474
* Resolve global policies (like timeout) with operational policies (like as_policy_read).
1475
*
1476
* @param p The policies to resolve
1477
*
1478
* @relates as_policies
1479
*/
1480
void
1481
as_policies_resolve
(
as_policies
* p);
1482
1483
#ifdef __cplusplus
1484
}
// end extern "C"
1485
#endif