1 /*- 2 * Copyright (c) 2009, 2020 Oracle and/or its affiliates. All rights reserved. 3 * 4 * See the file LICENSE for license information. 5 * 6 */ 7 using System; 8 using System.Collections.Generic; 9 using System.Text; 10 using BerkeleyDB.Internal; 11 12 namespace BerkeleyDB { 13 /// <summary> 14 /// A class representing configuration parameters for 15 /// <see cref="DatabaseEnvironment"/> 16 /// </summary> 17 public class DatabaseEnvironmentConfig { 18 /// <summary> 19 /// Create a new object with default settings 20 /// </summary> DatabaseEnvironmentConfig()21 public DatabaseEnvironmentConfig() { 22 DataDirs = new List<string>(); 23 } 24 25 /// <summary> 26 /// Configuration for the locking subsystem 27 /// </summary> 28 public LockingConfig LockSystemCfg; 29 /// <summary> 30 /// Configuration for the logging subsystem 31 /// </summary> 32 public LogConfig LogSystemCfg; 33 /// <summary> 34 /// Configuration for the memory pool subsystem 35 /// </summary> 36 public MPoolConfig MPoolSystemCfg; 37 /// <summary> 38 /// Configuration for the mutex subsystem 39 /// </summary> 40 public MutexConfig MutexSystemCfg; 41 /// <summary> 42 /// Configuration for the replication subsystem 43 /// </summary> 44 public ReplicationConfig RepSystemCfg; 45 46 /// <summary> 47 /// The mechanism for reporting detailed error messages to the 48 /// application. 49 /// </summary> 50 /// <remarks> 51 /// <para> 52 /// When an error occurs in the Berkeley DB library, a 53 /// <see cref="DatabaseException"/>, or subclass of DatabaseException, 54 /// is thrown. In some cases the exception may be insufficient 55 /// to completely describe the cause of the error, especially during 56 /// initial application debugging. 57 /// </para> 58 /// <para> 59 /// In some cases, when an error occurs, Berkeley DB calls the given 60 /// delegate with additional error information. It is up to the delegate 61 /// to display the error message in an appropriate manner. 62 /// </para> 63 /// <para> 64 /// Setting ErrorFeedback to NULL unconfigures the callback interface. 65 /// </para> 66 /// <para> 67 /// This error-logging enhancement does not slow performance or 68 /// significantly increase application size, and may be run during 69 /// normal operation as well as during application debugging. 70 /// </para> 71 /// </remarks> 72 public ErrorFeedbackDelegate ErrorFeedback; 73 /// <summary> 74 /// Monitor progress within long running operations. 75 /// </summary> 76 /// <remarks> 77 /// <para> 78 /// Some operations performed by the Berkeley DB library can take 79 /// non-trivial amounts of time. The Feedback delegate can be used by 80 /// applications to monitor progress within these operations. When an 81 /// operation is likely to take a long time, Berkeley DB will call the 82 /// specified delegate with progress information. 83 /// </para> 84 /// <para> 85 /// It is up to the delegate to display this information in an 86 /// appropriate manner. 87 /// </para> 88 /// </remarks> 89 public EnvironmentFeedbackDelegate Feedback; 90 /// <summary> 91 /// A delegate which is called to notify the process of specific 92 /// Berkeley DB events. 93 /// </summary> 94 public EventNotifyDelegate EventNotify; 95 /// <summary> 96 /// A delegate that returns a unique identifier pair for the current 97 /// thread of control. 98 /// </summary> 99 /// <remarks> 100 /// This delegate supports <see cref="DatabaseEnvironment.FailCheck"/>. 101 /// For more information, see Architecting Data Store and Concurrent 102 /// Data Store applications, and Architecting Transactional Data Store 103 /// applications, both in the Berkeley DB Programmer's Reference Guide. 104 /// </remarks> 105 public SetThreadIDDelegate SetThreadID; 106 /// <summary> 107 /// A delegate that formats a process ID and thread ID identifier pair. 108 /// </summary> 109 public SetThreadNameDelegate ThreadName; 110 /// <summary> 111 /// A delegate that returns if a thread of control (either a true thread 112 /// or a process) is still running. 113 /// </summary> 114 public ThreadIsAliveDelegate ThreadIsAlive; 115 116 /// <summary> 117 /// Paths of directories to be used as the location of the access method 118 /// database files. 119 /// </summary> 120 /// <remarks> 121 /// <para> 122 /// Paths specified to <see cref="Database.Open"/> are searched 123 /// relative to this path. Paths set using this method are additive, and 124 /// specifying more than one results in each specified directory 125 /// being searched for database files. 126 /// </para> 127 /// <para> 128 /// If no database directories are specified, database files must be 129 /// named either by absolute paths or relative to the environment home 130 /// directory. See Berkeley DB File Naming in the Programmer's Reference 131 /// Guide for more information. 132 /// </para> 133 /// </remarks> 134 public List<string> DataDirs; 135 /// <summary> 136 /// The path of a directory to be used as the location to create the 137 /// access method database files. When <see cref="BTreeDatabase.Open"/>, 138 /// <see cref="HashDatabase.Open"/>, <see cref="QueueDatabase.Open"/> or 139 /// <see cref="RecnoDatabase.Open"/> is used to create a file, it will be 140 /// created relative to this path. 141 /// </summary> 142 /// <remarks> 143 /// <para> 144 /// This path must also exist in <see cref="DataDirs"/>. 145 /// </para> 146 /// <para> 147 /// If no database directory is specified, database files must be named 148 /// either by absolute paths or relative to the environment home 149 /// directory. See Berkeley DB File Naming in the Programmer's Reference 150 /// Guide for more information. 151 /// </para> 152 /// </remarks> 153 public string CreationDir; 154 /// <summary> 155 /// The path of the directory where external files are stored, 156 /// replaces BlobFileDir. 157 /// </summary> 158 public string ExternalFileDir; 159 /// <summary> 160 /// Deprecated. Replaced by ExternalFileDir. 161 /// </summary> 162 public string BlobDir; 163 164 internal bool blobThresholdIsSet; 165 private uint blobThreshold; 166 /// <summary> 167 /// The size in bytes which is used to determine when a data item will 168 /// be stored as an external file. 169 /// <para> 170 /// Any data item that is equal to or larger in size than the 171 /// threshold value is automatically stored as an external file. 172 /// </para> 173 /// <para> 174 /// If the threshold value is 0, databases opened in the environment 175 /// default to never using external file support. 176 /// </para> 177 /// <para> 178 /// It is illegal to enable external file support in the environment if 179 /// any of <see cref="DatabaseEnvironmentConfig.TxnSnapshot"/>, 180 /// and <see cref="DatabaseEnvironmentConfig.UseMVCC"/> is set to true. 181 /// </para> 182 /// </summary> 183 public uint ExternalFileThreshold { 184 get { return blobThreshold; } 185 set { 186 blobThresholdIsSet = true; 187 blobThreshold = value; 188 } 189 } 190 /// <summary> 191 /// Deprecated. Replaced by ExternalFileThreshold. 192 /// </summary> 193 public uint BlobThreshold { 194 get { return blobThreshold; } 195 set { 196 blobThresholdIsSet = true; 197 blobThreshold = value; 198 } 199 } 200 201 internal bool encryptionIsSet; 202 private String encryptPwd; 203 private EncryptionAlgorithm encryptAlg; 204 /// <summary> 205 /// Set the password and algorithm used by the Berkeley DB library to 206 /// perform encryption and decryption. 207 /// </summary> 208 /// <param name="password"> 209 /// The password used to perform encryption and decryption. 210 /// </param> 211 /// <param name="alg"> 212 /// The algorithm used to perform encryption and decryption. 213 /// </param> SetEncryption(String password, EncryptionAlgorithm alg)214 public void SetEncryption(String password, EncryptionAlgorithm alg) { 215 encryptionIsSet = true; 216 encryptPwd = password; 217 encryptAlg = alg; 218 } 219 /// <summary> 220 /// The password used to perform encryption and decryption. 221 /// </summary> 222 public string EncryptionPassword { get { return encryptPwd; } } 223 /// <summary> 224 /// The algorithm used to perform encryption and decryption. 225 /// </summary> 226 public EncryptionAlgorithm EncryptAlgorithm { 227 get { return encryptAlg; } 228 } 229 230 /// <summary> 231 /// The prefix string that appears before error messages issued by 232 /// Berkeley DB. 233 /// </summary> 234 /// <remarks> 235 /// <para> 236 /// For databases opened inside of a DatabaseEnvironment, setting 237 /// ErrorPrefix affects the entire environment and is equivalent to 238 /// setting <see cref="DatabaseEnvironment.ErrorPrefix"/>. 239 /// </para> 240 /// </remarks> 241 public string ErrorPrefix; 242 /// <summary> 243 /// The prefix string that appears before informational messages issued 244 /// by Berkeley DB. 245 /// </summary> 246 /// <remarks> 247 /// <para> 248 /// For databases opened inside of a DatabaseEnvironment, setting 249 /// MessagePrefix affects the entire environment and is equivalent to 250 /// setting <see cref="DatabaseEnvironment.MessagePrefix"/>. 251 /// </para> 252 /// </remarks> 253 public string MessagePrefix; 254 /// <summary> 255 /// The permissions for any intermediate directories created by Berkeley 256 /// DB. 257 /// </summary> 258 /// <remarks> 259 /// <para> 260 /// By default, Berkeley DB does not create intermediate directories 261 /// needed for recovery. For example, if the file /a/b/c/mydatabase is being 262 /// recovered, and the directory path b/c does not exist, recovery 263 /// fails. This occurs because Berkeley DB does not know 264 /// what permissions are appropriate for intermediate directory 265 /// creation, and creating the directory might result in a security 266 /// problem. 267 /// </para> 268 /// <para> 269 /// Directory permissions are interpreted as a string of nine 270 /// characters, using the character set r (read), w (write), x (execute 271 /// or search), and - (none). The first character is the read 272 /// permissions for the directory owner (set to either r or -). The 273 /// second character is the write permissions for the directory owner 274 /// (set to either w or -). The third character is the execute 275 /// permissions for the directory owner (set to either x or -). 276 /// </para> 277 /// <para> 278 /// Similarly, the second set of three characters are the read, write 279 /// and execute/search permissions for the directory group, and the 280 /// third set of three characters are the read, write and execute/search 281 /// permissions for all others. For example, the string rwx------ would 282 /// configure read, write and execute/search access for the owner only. 283 /// The string rwxrwx--- would configure read, write and execute/search 284 /// access for both the owner and the group. The string rwxr----- would 285 /// configure read, write and execute/search access for the directory 286 /// owner and read-only access for the directory group. 287 /// </para> 288 /// </remarks> 289 public string IntermediateDirMode; 290 291 internal bool lckTimeoutIsSet; 292 private uint lckTimeout; 293 /// <summary> 294 /// A value, in microseconds, representing lock timeouts. 295 /// </summary> 296 /// <remarks> 297 /// <para> 298 /// All timeouts are checked whenever a thread of control blocks on a 299 /// lock or when deadlock detection is performed. As timeouts are only 300 /// checked when the lock request first blocks or when deadlock 301 /// detection is performed, the accuracy of the timeout depends on how 302 /// often deadlock detection is performed. 303 /// </para> 304 /// <para> 305 /// Timeout values specified for the database environment may be 306 /// overridden on a per-transaction basis, see 307 /// <see cref="Transaction.SetLockTimeout"/>. 308 /// </para> 309 /// </remarks> 310 public uint LockTimeout { 311 get { return lckTimeout; } 312 set { 313 lckTimeoutIsSet = true; 314 lckTimeout = value; 315 } 316 } 317 318 internal bool maxTxnsIsSet; 319 private uint maxTxns; 320 /// <summary> 321 /// The number of active transactions supported by the environment. This 322 /// value bounds the size of the memory allocated for transactions. 323 /// Child transactions are counted as active until they either commit or 324 /// abort. 325 /// </summary> 326 /// <remarks> 327 /// <para> 328 /// Transactions that update multiversion databases are not freed until 329 /// the last page version that the transaction created is flushed from 330 /// cache. This means that applications using multi-version concurrency 331 /// control may need in the extreme case a transaction for each page in cache. 332 /// </para> 333 /// <para> 334 /// When all of the memory available in the database environment for 335 /// transactions is in use, calls to 336 /// <see cref="DatabaseEnvironment.BeginTransaction"/> fail (until 337 /// some active transactions complete). If MaxTransactions is never set, 338 /// the database environment is configured to support at least 100 339 /// active transactions. 340 /// </para> 341 /// </remarks> 342 public uint MaxTransactions { 343 get { return maxTxns; } 344 set { 345 maxTxnsIsSet = true; 346 maxTxns = value; 347 } 348 } 349 350 /// <summary> 351 /// The path of a directory to be used as the location to store 352 /// the persistent metadata. 353 /// </summary> 354 /// <remarks> 355 /// <para> 356 /// By default, metadata is stored in the environment home directory. 357 /// See Berkeley DB File Naming in the Programmer's Reference Guide for 358 /// more information. 359 /// </para> 360 /// <para> 361 /// When used in a replicated application, the metadata directory must 362 /// be the same location for all sites within a replication group. 363 /// </para> 364 /// </remarks> 365 public string MetadataDir; 366 367 /// <summary> 368 /// The path of a directory to be used as the location for temporary 369 /// files. 370 /// </summary> 371 /// <remarks> 372 /// <para> 373 /// The files created to back in-memory access method databases are 374 /// created relative to this path. These temporary files can be quite 375 /// large, depending on the size of the database. 376 /// </para> 377 /// <para> 378 /// If no directories are specified, the following alternatives are 379 /// checked in the specified order. The first existing directory path is 380 /// used for all temporary files. 381 /// </para> 382 /// <list type="number"> 383 /// <item>The value of the environment variable TMPDIR.</item> 384 /// <item>The value of the environment variable TEMP.</item> 385 /// <item>The value of the environment variable TMP.</item> 386 /// <item>The value of the environment variable TempFolder.</item> 387 /// <item>The value returned by the GetTempPath interface.</item> 388 /// <item>The directory /var/tmp.</item> 389 /// <item>The directory /usr/tmp.</item> 390 /// <item>The directory /temp.</item> 391 /// <item>The directory /tmp.</item> 392 /// <item>The directory C:/temp.</item> 393 /// <item>The directory C:/tmp.</item> 394 /// </list> 395 /// <para> 396 /// Environment variables are only checked if 397 /// <see cref="UseEnvironmentVars"/> is true. 398 /// </para> 399 /// </remarks> 400 public string TempDir; 401 402 internal bool threadCntIsSet; 403 private uint threadCnt; 404 /// <summary> 405 /// An approximate number of threads in the database environment. 406 /// </summary> 407 /// <remarks> 408 /// <para> 409 /// ThreadCount must set if <see cref="DatabaseEnvironment.FailCheck"/> 410 /// is used. ThreadCount does not set the maximum number of threads. 411 /// It is used to determine memory sizing and the thread control block 412 /// reclamation policy. 413 /// </para> 414 /// <para> 415 /// If a process has not configured <see cref="ThreadIsAlive"/>, and 416 /// then attempts to join a database environment configured for failure 417 /// checking with <see cref="DatabaseEnvironment.FailCheck"/>, 418 /// <see cref="SetThreadID"/>, <see cref="ThreadIsAlive"/> and 419 /// ThreadCount, the program may be unable to allocate a thread control 420 /// block and fail to join the environment. This is true of the 421 /// standalone Berkeley DB utility programs. To avoid problems when 422 /// using the standalone Berkeley DB utility programs with environments 423 /// configured for failure checking, incorporate the utility's 424 /// functionality directly in the application, or call 425 /// <see cref="DatabaseEnvironment.FailCheck"/> before running the 426 /// utility. 427 /// </para> 428 /// </remarks> 429 public uint ThreadCount { 430 get { return threadCnt; } 431 set { 432 threadCntIsSet = true; 433 threadCnt = value; 434 } 435 } 436 437 private uint _initdatabasecount; 438 internal bool initDatabaseCountIsSet; 439 /// <summary> 440 /// The initial number of databases catered for by the Berkeley 441 /// DB environment 442 /// </summary> 443 /// <remarks> 444 /// The value is used by <see cref="DatabaseEnvironment.Open"/> to 445 /// force Berkeley DB to allocate a certain number of databases 446 /// when the environment is created. This can be useful to calculate 447 /// the initial amount of space needed for the replication objects 448 /// in the main environment region. 449 /// </remarks> 450 public uint InitDatabaseCount { 451 get { return _initdatabasecount; } 452 set { 453 initDatabaseCountIsSet = true; 454 _initdatabasecount = value; 455 } 456 } 457 458 private uint _initdatabaselength; 459 internal bool initDatabaseLengthIsSet; 460 /// <summary> 461 /// The initial maximum combined length of a database's directory 462 /// and name catered for by the Berkeley DB environment 463 /// </summary> 464 /// <remarks> 465 /// The value is used by <see cref="DatabaseEnvironment.Open"/> to 466 /// force Berkeley DB to allocate the maximum combined length of a 467 /// database's directory and name strings when the environment is 468 /// created. This can be useful to calculate the initial amount of 469 /// space needed for the replication objects in the main environment 470 /// region. 471 /// </remarks> 472 public uint InitDatabaseLength 473 { 474 get { return _initdatabaselength; } 475 set { 476 initDatabaseLengthIsSet = true; 477 _initdatabaselength = value; 478 } 479 } 480 481 private uint _initextfiledatabasecount; 482 internal bool initExtFileDatabaseCountIsSet; 483 /// <summary> 484 /// The initial number of databases and subdatabases using external 485 /// files catered for by the Berkeley DB environment 486 /// </summary> 487 /// <remarks> 488 /// The value is used by <see cref="DatabaseEnvironment.Open"/> to 489 /// force Berkeley DB to allocate the initial number of databases 490 /// and subdatabases using external files when the environment is 491 /// created. This can be useful to calculate the initial amount 492 /// of space needed for the replication objects in the main 493 /// environment region. 494 /// </remarks> 495 public uint InitExtFileDatabaseCount 496 { 497 get { return _initextfiledatabasecount; } 498 set { 499 initExtFileDatabaseCountIsSet = true; 500 _initextfiledatabasecount = value; 501 } 502 } 503 504 private uint _initrepsitescount; 505 internal bool initRepSitesCountIsSet; 506 /// <summary> 507 /// The initial maximum number of sites in the replication group 508 /// catered for by the Berkeley DB environment. 509 /// </summary> 510 /// <remarks> 511 /// The value is used by <see cref="DatabaseEnvironment.Open"/> to 512 /// to allocate the initial maximum number of sites when the 513 /// environment is created. This can be useful to calculate the 514 /// initial amount of space needed for the replication objects 515 /// in the main environment region. 516 /// </remarks> 517 public uint InitRepSitesCount 518 { 519 get { return _initrepsitescount; } 520 set { 521 initRepSitesCountIsSet = true; 522 _initrepsitescount = value; 523 } 524 } 525 526 private uint _initthreadcount; 527 internal bool initThreadCountIsSet; 528 /// <summary> 529 /// The initial number of concurrent threads catered for by the 530 /// Berkeley DB environment 531 /// </summary> 532 /// <remarks> 533 /// <para> 534 /// This value is used by <see cref="DatabaseEnvironment.Open"/> to 535 /// force Berkeley DB to allocate a certain number of thread 536 /// objects when the environment is created. This can be useful if an 537 /// application uses a large number of thread objects, and 538 /// experiences performance issues with the default dynamic allocation 539 /// algorithm. 540 /// </para> 541 /// <para> 542 /// If the database environment already exists when 543 /// <see cref="DatabaseEnvironment.Open"/> is called, the value of 544 /// InitLockers is ignored. 545 /// </para> 546 /// </remarks> 547 public uint InitThreadCount { 548 get { return _initthreadcount; } 549 set { 550 initThreadCountIsSet = true; 551 _initthreadcount = value; 552 } 553 } 554 555 private uint _inittxncount; 556 internal bool initTxnCountIsSet; 557 /// <summary> 558 /// The initial number of transactions catered for by the Berkeley DB 559 /// environment 560 /// </summary> 561 /// <remarks> 562 /// <para> 563 /// This value is used by <see cref="DatabaseEnvironment.Open"/> to 564 /// force Berkeley DB to allocate a certain number of transaction 565 /// objects when the environment is created. This can be useful if an 566 /// application uses a large number of transaction objects, and 567 /// experiences performance issues with the default dynamic allocation 568 /// algorithm. 569 /// </para> 570 /// <para> 571 /// If the database environment already exists when 572 /// <see cref="DatabaseEnvironment.Open"/> is called, the value of 573 /// InitLockers is ignored. 574 /// </para> 575 /// </remarks> 576 public uint InitTxnCount { 577 get { return _inittxncount; } 578 set { 579 initTxnCountIsSet = true; 580 _inittxncount = value; 581 } 582 } 583 584 internal bool txnTimeoutIsSet; 585 private uint _txnTimeout; 586 /// <summary> 587 /// A value, in microseconds, representing transaction timeouts. 588 /// </summary> 589 /// <remarks> 590 /// <para> 591 /// All timeouts are checked whenever a thread of control blocks on a 592 /// lock or when deadlock detection is performed. As timeouts are only 593 /// checked when the lock request first blocks or when deadlock 594 /// detection is performed, the accuracy of the timeout depends on how 595 /// often deadlock detection is performed. 596 /// </para> 597 /// <para> 598 /// Timeout values specified for the database environment may be 599 /// overridden on a per-transaction basis, see 600 /// <see cref="Transaction.SetTxnTimeout"/>. 601 /// </para> 602 /// </remarks> 603 public uint TxnTimeout { 604 get { return _txnTimeout; } 605 set { 606 txnTimeoutIsSet = true; 607 _txnTimeout = value; 608 } 609 } 610 611 internal bool txnTimestampIsSet; 612 private DateTime _txnTimestamp; 613 /// <summary> 614 /// Recover to the time specified by timestamp rather than to the most 615 /// current possible date. 616 /// </summary> 617 /// <remarks> 618 /// <para> 619 /// Once a database environment has been upgraded to a new version of 620 /// Berkeley DB involving a log format change (see Upgrading Berkeley DB 621 /// installations in the Programmer's Reference Guide), it is no longer 622 /// possible to recover to a specific time before that upgrade. 623 /// </para> 624 /// </remarks> 625 public DateTime TxnTimestamp { 626 get { return _txnTimestamp; } 627 set { 628 txnTimestampIsSet = true; 629 _txnTimestamp = value; 630 } 631 } 632 633 /// <summary> 634 /// Specific additional informational and debugging messages in the 635 /// Berkeley DB message output. 636 /// </summary> 637 public VerboseMessages Verbosity = new VerboseMessages(); 638 639 /* Fields for set_flags() */ 640 /// <summary> 641 /// If true, database operations for which no explicit transaction 642 /// handle was specified, and which modify databases in the database 643 /// environment, are automatically enclosed within a transaction. 644 /// </summary> 645 public bool AutoCommit; 646 /// <summary> 647 /// If true, Berkeley DB Concurrent Data Store applications perform 648 /// locking on an environment-wide basis rather than on a per-database 649 /// basis. 650 /// </summary> 651 public bool CDB_ALLDB; 652 /// <summary> 653 /// If true, Berkeley DB flushes database writes to the backing disk 654 /// before returning from the write system call, rather than flushing 655 /// database writes explicitly in a separate system call, as necessary. 656 /// </summary> 657 /// <remarks> 658 /// This is only available on some systems (for example, systems 659 /// supporting the IEEE/ANSI Std 1003.1 (POSIX) standard O_DSYNC flag, 660 /// or systems supporting the Windows FILE_FLAG_WRITE_THROUGH flag). 661 /// This flag may result in inaccurate file modification times and other 662 /// file-level information for Berkeley DB database files. This flag 663 /// almost certainly results in a performance decrease on most 664 /// systems. This flag is only applicable to certain filesystems (for 665 /// example, the Veritas VxFS filesystem), where the filesystem's 666 /// support for trickling writes back to stable storage behaves badly 667 /// (or more likely, has been misconfigured). 668 /// </remarks> 669 public bool ForceFlush; 670 /// 671 /// <summary> Set a flag in the environment indicating that a 672 /// hot backup is in progress. 673 /// </summary> 674 /// <remarks> 675 /// When a "hot backup" copy of a database environment is taken, this 676 /// attribute should be configured in the environment prior to copying. 677 /// If any transactions with the bulk insert optimization enabled (i.e., 678 /// started with the Bulk configuration attribute) are in progress, 679 /// setting the HotBackupInProgress attribute forces a checkpoint in 680 /// the environment. After this attribute is set, the bulk insert 681 /// optimization is disabled, until the attribute is reset. Using this 682 /// protocol allows a hot backup procedure to make a consistent copy of 683 /// the database even when bulk transactions are ongoing. For more information 684 /// about hot backups see the Getting Started With Transactions Guide. To learn more 685 /// about the Bulk attribute see <see cref="TransactionConfig.Bulk"/>. 686 /// </remarks> 687 public bool HotbackupInProgress; 688 /// <summary> 689 /// If true, Berkeley DB page-faults shared regions into memory when 690 /// initially creating or joining a Berkeley DB environment. In 691 /// addition, Berkeley DB writes the shared regions when creating an 692 /// environment, forcing the underlying virtual memory and filesystems 693 /// to instantiate both the necessary memory and the necessary disk 694 /// space. This can also avoid out-of-disk space failures later on. 695 /// </summary> 696 /// <remarks> 697 /// <para> 698 /// In some applications, the expense of page-faulting the underlying 699 /// shared memory regions can affect performance. (For example, if the 700 /// page-fault occurs while holding a lock, other lock requests can 701 /// convoy, and overall throughput may decrease.) 702 /// </para> 703 /// </remarks> 704 public bool InitRegions; 705 /// <summary> 706 /// If true, turn off system buffering of Berkeley DB database files to 707 /// avoid double caching. 708 /// </summary> 709 public bool NoBuffer; 710 /// <summary> 711 /// If true, Berkeley DB grants all requested mutual exclusion 712 /// mutexes and database locks without regard for their actual 713 /// availability. This functionality should never be used for purposes 714 /// other than debugging. 715 /// </summary> 716 public bool NoLocking; 717 /// <summary> 718 /// If true, Berkeley DB copies read-only database files into the 719 /// local cache instead of potentially mapping them into process memory 720 /// (see <see cref="MPoolConfig.MMapSize"/> for further information). 721 /// </summary> 722 public bool NoMMap; 723 /// <summary> 724 /// If true, Berkeley DB ignores any panic state in the database 725 /// environment. (Database environments in a panic state normally refuse 726 /// all attempts to call Berkeley DB functions, throwing 727 /// <see cref="RunRecoveryException"/>. This functionality should never 728 /// be used for purposes other than debugging. 729 /// </summary> 730 public bool NoPanic; 731 /// <summary> 732 /// If true, overwrite files stored in encrypted formats before deleting 733 /// them. 734 /// </summary> 735 /// <remarks> 736 /// Berkeley DB overwrites files using alternating 0xff, 0x00 and 0xff 737 /// byte patterns. For an effective overwrite, the underlying 738 /// file must be stored on a fixed-block filesystem. Systems with 739 /// journaling or logging filesystems require operating system 740 /// support and probably modification of the Berkeley DB sources. 741 /// </remarks> 742 public bool Overwrite; 743 /// <summary> 744 /// If true, database calls timing out based on lock or transaction 745 /// timeout values throw <see cref="LockNotGrantedException"/> 746 /// instead of <see cref="DeadlockException"/>. This allows applications 747 /// to distinguish between operations which have deadlocked and 748 /// operations which have exceeded their time limits. 749 /// </summary> 750 public bool TimeNotGranted; 751 /// <summary> 752 /// If true, Berkeley DB does not write or synchronously flush the log 753 /// on transaction commit. 754 /// </summary> 755 /// <remarks> 756 /// This means that transactions exhibit the ACI (atomicity, 757 /// consistency, and isolation) properties, but not D (durability); 758 /// database integrity is maintained, but if the application or 759 /// system fails, it is possible that some number of the most recently 760 /// committed transactions may be undone during recovery. The number of 761 /// transactions at risk is governed by how many log updates can fit 762 /// into the log buffer, how often the operating system flushes dirty 763 /// buffers to disk, and how often the log is checkpointed. 764 /// </remarks> 765 public bool TxnNoSync; 766 /// <summary> 767 /// If true and a lock is unavailable for any Berkeley DB operation 768 /// performed in the context of a transaction, cause the operation to 769 /// throw <see cref="DeadlockException"/> (or 770 /// <see cref="LockNotGrantedException"/> if 771 /// <see cref="TimeNotGranted"/> is set. 772 /// </summary> 773 public bool TxnNoWait; 774 /// <summary> 775 /// If true, all transactions in the environment are started as if 776 /// <see cref="TransactionConfig.Snapshot"/> were passed to 777 /// <see cref="DatabaseEnvironment.BeginTransaction"/>, and all 778 /// non-transactional cursors are opened as if 779 /// <see cref="CursorConfig.SnapshotIsolation"/> were passed to 780 /// <see cref="BaseDatabase.Cursor"/>. 781 /// </summary> 782 public bool TxnSnapshot; 783 /// <summary> 784 /// If true, Berkeley DB writes, but does not synchronously flush, 785 /// the log on transaction commit. 786 /// </summary> 787 /// <remarks> 788 /// This means that transactions exhibit the ACI (atomicity, 789 /// consistency, and isolation) properties, but not D (durability); 790 /// database integrity is maintained, but if the system fails, 791 /// it is possible that some number of the most recently committed 792 /// transactions may be undone during recovery. The number of 793 /// transactions at risk is governed by how often the system flushes 794 /// dirty buffers to disk and how often the log is checkpointed. 795 /// </remarks> 796 public bool TxnWriteNoSync; 797 /// <summary> 798 /// If true, all databases in the environment are opened as if 799 /// <see cref="DatabaseConfig.UseMVCC"/> is passed to 800 /// <see cref="Database.Open"/>. This flag is ignored for queue 801 /// databases for which MVCC is not supported. 802 /// </summary> 803 public bool UseMVCC; 804 /// <summary> 805 /// If true, Berkeley DB yields the processor immediately after each 806 /// page or mutex acquisition. This functionality should never be used 807 /// for purposes other than stress testing. 808 /// </summary> 809 public bool YieldCPU; 810 internal uint flags { 811 get { 812 uint ret = 0; 813 ret |= AutoCommit ? DbConstants.DB_AUTO_COMMIT : 0; 814 ret |= CDB_ALLDB ? DbConstants.DB_CDB_ALLDB : 0; 815 ret |= ForceFlush ? DbConstants.DB_DSYNC_DB : 0; 816 ret |= HotbackupInProgress ? 817 DbConstants.DB_HOTBACKUP_IN_PROGRESS : 0; 818 ret |= InitRegions ? DbConstants.DB_REGION_INIT : 0; 819 ret |= NoBuffer ? DbConstants.DB_DIRECT_DB : 0; 820 ret |= NoLocking ? DbConstants.DB_NOLOCKING : 0; 821 ret |= NoMMap ? DbConstants.DB_NOMMAP : 0; 822 ret |= NoPanic ? DbConstants.DB_NOPANIC : 0; 823 ret |= Overwrite ? DbConstants.DB_OVERWRITE : 0; 824 ret |= TimeNotGranted ? DbConstants.DB_TIME_NOTGRANTED : 0; 825 ret |= TxnNoSync ? DbConstants.DB_TXN_NOSYNC : 0; 826 ret |= TxnNoWait ? DbConstants.DB_TXN_NOWAIT : 0; 827 ret |= TxnSnapshot ? DbConstants.DB_TXN_SNAPSHOT : 0; 828 ret |= TxnWriteNoSync ? DbConstants.DB_TXN_WRITE_NOSYNC : 0; 829 ret |= UseMVCC ? DbConstants.DB_MULTIVERSION : 0; 830 ret |= YieldCPU ? DbConstants.DB_YIELDCPU : 0; 831 return ret; 832 } 833 } 834 835 /* Fields for open() flags */ 836 /// <summary> 837 /// If true, Berkeley DB subsystems create any underlying files, as 838 /// necessary. 839 /// </summary> 840 public bool Create; 841 /// <summary> 842 /// If true, the created <see cref="DatabaseEnvironment"/> object is 843 /// free-threaded; that is, concurrently usable by multiple threads 844 /// in the address space. 845 /// </summary> 846 /// <remarks> 847 /// <para> 848 /// Required to be true if the created <see cref="DatabaseEnvironment"/> 849 /// object is concurrently used by more than one thread in the 850 /// process, or if any <see cref="Database"/> objects opened in the 851 /// scope of the <see cref="DatabaseEnvironment"/> object is 852 /// concurrently used by more than one thread in the process. 853 /// </para> 854 /// <para>Required to be true when using the Replication Manager.</para> 855 /// </remarks> 856 public bool FreeThreaded; 857 /// <summary> 858 /// If true, lock shared Berkeley DB environment files and memory-mapped 859 /// databases into memory. 860 /// </summary> 861 public bool Lockdown; 862 /// <summary> 863 /// If true, allocate region memory from the heap instead of from memory 864 /// backed by the filesystem or system shared memory. 865 /// </summary> 866 /// <remarks> 867 /// <para> 868 /// This setting implies the environment is only accessed by a 869 /// single process (although that process may be multithreaded). This 870 /// flag has two effects on the Berkeley DB environment. First, all 871 /// underlying data structures are allocated from per-process memory 872 /// instead of from shared memory that is accessible to more than a 873 /// single process. Second, mutexes are only configured to work between 874 /// threads. 875 /// </para> 876 /// <para> 877 /// This setting should be false if more than a single process is 878 /// accessing the environment because it is likely to cause database 879 /// corruption and unpredictable behavior. For example, if both a server 880 /// application and Berkeley DB utilities (for example, db_archive, 881 /// db_checkpoint or db_stat) are expected to access the environment, 882 /// this setting should be false. 883 /// </para> 884 /// </remarks> 885 public bool Private; 886 /// <summary> 887 /// If true, check to see if recovery needs to be performed before 888 /// opening the database environment. (For this check to be accurate, 889 /// all processes using the environment must specify it when opening the 890 /// environment.) 891 /// </summary> 892 /// <remarks> 893 /// If recovery needs to be performed for any reason (including the 894 /// initial use of this setting), and <see cref="RunRecovery"/>is also 895 /// specified, recovery is performed and the open proceeds 896 /// normally. If recovery needs to be performed and 897 /// <see cref="RunRecovery"/> is not specified, 898 /// <see cref="RunRecoveryException"/> is thrown. If recovery does 899 /// not need to be performed, <see cref="RunRecovery"/> is ignored. 900 /// See Architecting Transactional Data Store applications in the 901 /// Programmer's Reference Guide for more information. 902 /// </remarks> 903 public bool Register; 904 /// <summary> 905 /// If true, catastrophic recovery is run on this environment 906 /// before opening it for normal use. 907 /// </summary> 908 /// <remarks> 909 /// If true, the <see cref="Create"/> and <see cref="UseTxns"/> must 910 /// also be set, because the regions are going to be removed and re-created, 911 /// and transactions are required for application recovery. 912 /// </remarks> 913 public bool RunFatalRecovery; 914 /// <summary> 915 /// If true, normal recovery is run on this environment before 916 /// opening it for normal use. 917 /// </summary> 918 /// <remarks> 919 /// If true, the <see cref="Create"/> and <see cref="UseTxns"/> must 920 /// also be set, because the regions are going to be removed and re-created, 921 /// and transactions are required for application recovery. 922 /// </remarks> 923 public bool RunRecovery; 924 /// <summary> 925 /// If true, allocate region memory from system shared memory instead of 926 /// from heap memory or memory backed by the filesystem. 927 /// </summary> 928 /// <remarks> 929 /// See Shared Memory Regions in the Programmer's Reference Guide for 930 /// more information. 931 /// </remarks> 932 public bool SystemMemory; 933 /// <summary> 934 /// If true, the Berkeley DB process' environment may be permitted to 935 /// specify information to be used when naming files. 936 /// </summary> 937 /// <remarks> 938 /// <para> 939 /// See Berkeley DB File Naming in the Programmer's Reference Guide for 940 /// more information. 941 /// </para> 942 /// <para> 943 /// Because permitting users to specify which files are used can create 944 /// security problems, environment information is used in file 945 /// naming for all users only if UseEnvironmentVars is true. 946 /// </para> 947 /// </remarks> 948 public bool UseEnvironmentVars; 949 private bool USE_ENVIRON_ROOT = false; 950 /// <summary> 951 /// If true, initialize locking for the Berkeley DB Concurrent Data 952 /// Store product. 953 /// </summary> 954 /// <remarks> 955 /// In this mode, Berkeley DB provides multiple reader/single writer 956 /// access. The only other subsystem that should be specified with 957 /// UseCDB flag is <see cref="UseMPool"/>. 958 /// </remarks> 959 public bool UseCDB; 960 /// <summary> 961 /// If true, initialize the locking subsystem. 962 /// </summary> 963 /// <remarks> 964 /// This subsystem should be used when multiple processes or threads are 965 /// going to be reading and writing a Berkeley DB database, so that they 966 /// do not interfere with each other. If all threads are accessing the 967 /// database(s) read-only, locking is unnecessary. When UseLocking is 968 /// specified, it is usually necessary to run a deadlock detector, as 969 /// well. See <see cref="DatabaseEnvironment.DetectDeadlocks"/> for more 970 /// information. 971 /// </remarks> 972 public bool UseLocking; 973 /// <summary> 974 /// If true, initialize the logging subsystem. 975 /// </summary> 976 /// <remarks> 977 /// This subsystem should be used when recovery from application or 978 /// system failure is necessary. If the log region is being created and 979 /// log files are already present, the log files are reviewed; 980 /// subsequent log writes are appended to the end of the log, rather 981 /// than overwriting current log entries. 982 /// </remarks> 983 public bool UseLogging; 984 /// <summary> 985 /// If true, initialize the shared memory buffer pool subsystem. 986 /// </summary> 987 /// <remarks> 988 /// This subsystem should be used whenever an application is using any 989 /// Berkeley DB access method. 990 /// </remarks> 991 public bool UseMPool; 992 /// <summary> 993 /// If true, initialize the replication subsystem. 994 /// </summary> 995 /// <remarks> 996 /// This subsystem should be used whenever an application plans on using 997 /// replication. UseReplication requires <see cref="UseTxns"/> and 998 /// <see cref="UseLocking"/> also be set. 999 /// </remarks> 1000 public bool UseReplication; 1001 /// <summary> 1002 /// If true, initialize the transaction subsystem. 1003 /// </summary> 1004 /// <remarks> 1005 /// This subsystem should be used when recovery and atomicity of 1006 /// multiple operations are important. UseTxns implies 1007 /// <see cref="UseLogging"/>. 1008 /// </remarks> 1009 public bool UseTxns; 1010 internal uint openFlags { 1011 get { 1012 uint ret = 0; 1013 ret |= Create ? DbConstants.DB_CREATE : 0; 1014 ret |= FreeThreaded ? DbConstants.DB_THREAD : 0; 1015 ret |= Lockdown ? DbConstants.DB_LOCKDOWN : 0; 1016 ret |= Private ? DbConstants.DB_PRIVATE : 0; 1017 ret |= Register ? DbConstants.DB_REGISTER : 0; 1018 ret |= RunFatalRecovery ? DbConstants.DB_RECOVER_FATAL : 0; 1019 ret |= RunRecovery ? DbConstants.DB_RECOVER : 0; 1020 ret |= SystemMemory ? DbConstants.DB_SYSTEM_MEM : 0; 1021 ret |= UseEnvironmentVars ? DbConstants.DB_USE_ENVIRON : 0; 1022 ret |= USE_ENVIRON_ROOT ? DbConstants.DB_USE_ENVIRON_ROOT : 0; 1023 ret |= UseCDB ? DbConstants.DB_INIT_CDB : 0; 1024 ret |= UseLocking ? DbConstants.DB_INIT_LOCK : 0; 1025 ret |= UseLogging ? DbConstants.DB_INIT_LOG : 0; 1026 ret |= UseMPool ? DbConstants.DB_INIT_MPOOL : 0; 1027 ret |= UseReplication ? DbConstants.DB_INIT_REP : 0; 1028 ret |= UseTxns ? DbConstants.DB_INIT_TXN : 0; 1029 return ret; 1030 } 1031 } 1032 } 1033 } 1034