1 module fdb.fdb_c_options; 2 3 enum NetworkOption : uint 4 { 5 // deprecated 6 NONE = 0, 7 8 // deprecated 9 LOCAL_ADDRESS = 10, 10 11 // deprecated 12 CLUSTER_FILE = 20, 13 14 /** 15 * Enables trace output to a file in a directory of the clients choosing 16 * Parameter: (String) path to output directory (or NULL for current 17 * working directory) 18 */ 19 TRACE_ENABLE = 30, 20 21 /** 22 * Sets the maximum size in bytes of a single trace output file. 23 * This value should be in the range ``[0, long.max]``. 24 * If the value is set to 0, there is no limit on individual file size. 25 * The default is a maximum size of 10,485,760 bytes. 26 * Parameter: (Int64) max size of a single trace output file 27 */ 28 TRACE_ROLL_SIZE = 31, 29 30 /** 31 * Sets the maximum size of a all the trace output files put together. 32 * This value should be in the range ``[0, long.max]``. 33 * If the value is set to 0, there is no limit on the total size of the 34 * files. 35 * The default is a maximum size of 104,857,600 bytes. 36 * If the default roll size is used, this means that a maximum of 10 trace 37 * files will be written at a time. 38 * Parameter: (Int64) max total size of trace files 39 */ 40 TRACE_MAX_LOG_SIZE = 32, 41 42 /** 43 * Set internal tuning or debugging knobs 44 * Parameter: (String) knob_name=knob_value 45 */ 46 KNOB = 40, 47 48 /** 49 * Set the TLS plugin to load. This option, if used, must be set before any 50 * other TLS options 51 * Parameter: (String) file path or linker-resolved name 52 */ 53 TLS_PLUGIN, 54 55 /** 56 * Set the certificate chain 57 * Parameter: (Bytes) certificates 58 */ 59 TLS_CERT_BYTES, 60 61 /** 62 * Set the file from which to load the certificate chain 63 * Parameter: (String) file path 64 */ 65 TLS_CERT_PATH, 66 67 /** 68 * Set the private key corresponding to your own certificate 69 * Parameter: (Bytes) key 70 */ 71 TLS_KEY_BYTES = 45, 72 73 /** 74 * Set the file from which to load the private key corresponding to your 75 * own certificate 76 * Parameter: (String) file path 77 */ 78 TLS_KEY_PATH, 79 80 /** 81 * Set the peer certificate field verification criteria 82 * Parameter: (Bytes) verification pattern 83 */ 84 TLS_VERIFY_PEERS, 85 } 86 87 enum ClusterOption : uint 88 { 89 /** 90 * This option is only a placeholder for C compatibility and should not be 91 * used 92 * Parameter: Option takes no parameter 93 */ 94 DUMMY_DO_NOT_USE = -1, 95 } 96 97 enum DatabaseOption : uint 98 { 99 /** 100 * Set the size of the client location cache. Raising this value can boost 101 * performance in very large databases where clients access data in a near- 102 * random pattern. Defaults to 100000. 103 * Parameter: (Int) Max location cache entries 104 */ 105 LOCATION_CACHE_SIZE = 10, 106 107 /** 108 * Set the maximum number of watches allowed to be outstanding on a database 109 * connection. Increasing this number could result in increased resource 110 * usage. Reducing this number will not cancel any outstanding watches. 111 * Defaults to 10000 and cannot be larger than 1000000. 112 * Parameter: (Int) Max outstanding watches 113 */ 114 MAX_WATCHES = 20, 115 116 /** 117 * Specify the machine ID that was passed to fdbserver processes running on 118 * the same machine as this client, for better location-aware load 119 * balancing. 120 * Parameter: (String) Hexadecimal ID 121 */ 122 MACHINE_ID, 123 124 /** 125 * Specify the datacenter ID that was passed to fdbserver processes running 126 * in the same datacenter as this client, for better location-aware load 127 * balancing. 128 * Parameter: (String) Hexadecimal ID 129 */ 130 DATACENTER_ID, 131 } 132 133 enum TransactionOption : uint 134 { 135 /** 136 * The transaction, if not self-conflicting, may be committed a second time 137 * after commit succeeds, in the event of a fault 138 */ 139 CAUSAL_WRITE_RISKY = 10, 140 141 /** 142 * The read version will be committed, and usually will be the latest 143 * committed, but might not be the latest committed in the event of a fault 144 * or partition 145 */ 146 CAUSAL_READ_RISKY = 20, 147 148 CAUSAL_READ_DISABLE = 21, 149 150 /** 151 * The next write performed on this transaction will not generate a write 152 * conflict range. As a result, other transactions which read the key(s) 153 * being modified by the next write will not conflict with this transaction. 154 * Care needs to be taken when using this option on a transaction that is 155 * shared between multiple threads. When setting this option, write conflict 156 * ranges will be disabled on the next write operation, regardless of what 157 * thread it is on. 158 */ 159 NEXT_WRITE_NO_WRITE_CONFLICT_RANGE = 30, 160 161 CHECK_WRITES_ENABLE = 50, 162 163 /** 164 * Reads performed by a transaction will not see any prior mutations that 165 * occured in that transaction, instead seeing the value which was in the 166 * database at the transaction's read version. This option may provide a 167 * small performance benefit for the client, but also disables a number of 168 * client-side optimizations which are beneficial for transactions which 169 * tend to read and write the same keys within a single transaction. 170 */ 171 READ_YOUR_WRITES_DISABLE = 51, 172 173 /** 174 * Disables read-ahead caching for range reads. Under normal operation, a 175 * transaction will read extra rows from the database into cache if range 176 * reads are used to page through a series of data one row at a time (i.e. 177 * if a range read with a one row limit is followed by another one row range 178 * read starting immediately after the result of the first). 179 */ 180 READ_AHEAD_DISABLE = 52, 181 182 DURABILITY_DATACENTER = 110, 183 DURABILITY_RISKY = 120, 184 DURABILITY_DEV_NULL_IS_WEB_SCALE = 130, 185 186 /** 187 * Specifies that this transaction should be treated as highest priority 188 * and that lower priority transactions should block behind this one. Use is 189 * discouraged outside of low-level tools 190 */ 191 PRIORITY_SYSTEM_IMMEDIATE = 200, 192 193 /** 194 * Specifies that this transaction should be treated as low priority and 195 * that default priority transactions should be processed first. Useful for 196 * doing batch work simultaneously with latency-sensitive work 197 */ 198 PRIORITY_BATCH = 201, 199 200 /** 201 * This is a write-only transaction which sets the initial configuration 202 */ 203 INITIALIZE_NEW_DATABASE = 300, 204 205 /** 206 * Allows this transaction to read and modify system keys (those that start 207 * with the byte 0xFF) 208 */ 209 ACCESS_SYSTEM_KEYS = 301, 210 211 /** 212 * Allows this transaction to read system keys (those that start with the 213 * byte 0xFF) 214 */ 215 READ_SYSTEM_KEYS = 302, 216 217 DEBUG_DUMP = 400, 218 219 /** 220 * Parameter: (String) Optional transaction name 221 */ 222 DEBUG_RETRY_LOGGING = 401, 223 224 /** 225 * Set a timeout in milliseconds which, when elapsed, will cause the 226 * transaction automatically to be cancelled. Valid parameter values are 227 * ``[0, INT_MAX]``. If set to 0, will disable all timeouts. All pending and 228 * any future uses of the transaction will throw an exception. The 229 * transaction can be used again after it is reset. Like all transaction 230 * options, a timeout must be reset after a call to onError. This behavior 231 * allows the user to make the timeout dynamic. 232 * Parameter: (Int32) value in milliseconds of timeout 233 */ 234 TIMEOUT = 500, 235 236 /** 237 * Set a maximum number of retries after which additional calls to onError 238 * will throw the most recently seen error code. Valid parameter values are 239 * ``[-1, INT_MAX]``. If set to -1, will disable the retry limit. Like all 240 * transaction options, the retry limit must be reset after a call to 241 * onError. This behavior allows the user to make the retry limit dynamic. 242 * Parameter: (Int32) number of times to retry 243 */ 244 RETRY_LIMIT = 501, 245 246 /** 247 * Set the maximum amount of backoff delay incurred in the call to onError 248 * if the error is retryable. 249 * Defaults to 1000 ms. Valid parameter values are [0, int.MaxValue]. 250 * Like all transaction options, the maximum retry delay must be reset 251 * after a call to onError. 252 * If the maximum retry delay is less than the current retry delay of the 253 * transaction, then the current retry delay will be clamped to the maximum 254 * retry delay. 255 * Parameter: (Int32) value in milliseconds of maximum delay 256 */ 257 MAX_RETRY_DELAY = 502, 258 259 /** 260 * Snapshot read operations will see the results of writes done in the same 261 * transaction. 262 */ 263 SNAPSHOT_READ_YOUR_WRITE_ENABLE = 600, 264 265 /** 266 * Snapshot read operations will not see the results of writes done in the 267 * same transaction. 268 */ 269 SNAPSHOT_READ_YOUR_WRITE_DISABLE = 601, 270 } 271 272 enum StreamingMode : int 273 { 274 /** 275 * Client intends to consume the entire range and would like it all 276 * transferred as early as possible. 277 */ 278 WANT_ALL = -2, 279 280 /** 281 * The default. The client doesn't know how much of the range it is likely 282 * to used and wants different performance concerns to be balanced. Only a 283 * small portion of data is transferred to the client initially (in order to 284 * minimize costs if the client doesn't read the entire range), and as the 285 * caller iterates over more items in the range larger batches will be 286 * transferred in order to minimize latency. 287 */ 288 ITERATOR, 289 290 /** 291 * Infrequently used. The client has passed a specific row limit and wants 292 * that many rows delivered in a single batch. Because of iterator operation 293 * in client drivers make request batches transparent to the user, consider 294 * ``WANT_ALL`` StreamingMode instead. A row limit must be specified if this 295 * mode is used. 296 */ 297 EXACT, 298 299 /** 300 * Infrequently used. Transfer data in batches small enough to not be much 301 * more expensive than reading individual rows, to minimize cost if 302 * iteration stops early. 303 */ 304 SMALL, 305 306 /** 307 * Infrequently used. Transfer data in batches sized in between small and 308 * large. 309 */ 310 MEDIUM, 311 312 /** 313 * Infrequently used. Transfer data in batches large enough to be, in a 314 * high-concurrency environment, nearly as efficient as possible. If the 315 * client stops iteration early, some disk and network bandwidth may be 316 * wasted. The batch size may still be too small to allow a single client to 317 * get high throughput from the database, so if that is what you need 318 * consider the SERIAL StreamingMode. 319 */ 320 LARGE, 321 322 /** 323 * Transfer data in batches large enough that an individual client can get 324 * reasonable read bandwidth from the database. If the client stops 325 * iteration early, considerable disk and network bandwidth may be wasted. 326 */ 327 SERIAL, 328 } 329 330 enum MutationType : uint 331 { 332 /** 333 * Performs an addition of little-endian integers. If the existing value in 334 * the database is not present or shorter than ``param``, it is first 335 * extended to the length of ``param`` with zero bytes. If ``param`` is 336 * shorter than the existing value in the database, the existing value is 337 * truncated to match the length of ``param``. The integers to be added must 338 * be stored in a little-endian representation. They can be signed in two's 339 * complement representation or unsigned. You can add to an integer at a 340 * known offset in the value by prepending the appropriate number of zero 341 * bytes to ``param`` and padding with zero bytes to match the length of the 342 * value. However, this offset technique requires that you know the addition 343 * will not cause the integer field within the value to overflow. 344 */ 345 ADD = 2, 346 347 // deprecated 348 AND = 6, 349 350 /** 351 * Performs a bitwise ``and`` operation. If the existing value in the 352 * database is not present or shorter than ``param``, it is first extended 353 * to the length of ``param`` with zero bytes. If ``param`` is shorter than 354 * the existing value in the database, the existing value is truncated to 355 * match the length of ``param``. 356 */ 357 BIT_AND = 6, 358 359 // deprecated 360 OR, 361 362 /** 363 * Performs a bitwise ``or`` operation. If the existing value in the 364 * database is not present or shorter than ``param``, it is first extended 365 * to the length of ``param`` with zero bytes. If ``param`` is shorter than 366 * the existing value in the database, the existing value is truncated to 367 * match the length of ``param``. 368 */ 369 BIT_OR = 7, 370 371 // deprecated 372 XOR, 373 374 /** 375 * Performs a bitwise ``xor`` operation. If the existing value in the 376 * database is not present or shorter than ``param``, it is first extended 377 * to the length of ``param`` with zero bytes. If ``param`` is shorter than 378 * the existing value in the database, the existing value is truncated to 379 * match the length of ``param``. 380 */ 381 BIT_XOR = 8, 382 383 /** 384 * Performs a little-endian comparison of byte strings. 385 * If the existing value in the database is not present or shorter than 386 * ``param``, it is first extended to the length of ``param`` with zero 387 * bytes. 388 * If ``param`` is shorter than the existing value in the database, the 389 * existing value is truncated to match the length of ``param``. 390 * The larger of the two values is then stored in the database. 391 */ 392 MAX = 12, 393 394 /** 395 * Performs a little-endian comparison of byte strings. 396 * If the existing value in the database is not present or shorter than 397 * ``param``, it is first extended to the length of ``param`` with zero 398 * bytes. 399 * If ``param`` is shorter than the existing value in the database, the 400 * existing value is truncated to match the length of ``param``. 401 * The smaller of the two values is then stored in the database. 402 */ 403 MIN = 13 404 } 405 406 enum ConflictRangeType : uint 407 { 408 /** 409 * Used to add a read conflict range 410 */ 411 READ, 412 413 /** 414 * Used to add a write conflict range 415 */ 416 WRITE, 417 }