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