lang/csharp/src/LogConfig.cs

   1 /*-
   2  * See the file LICENSE for redistribution information.
   3  *
   4  * Copyright (c) 2009, 2012 Oracle and/or its affiliates.  All rights reserved.
   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 a
  15     /// <see cref="DatabaseEnvironment"/>'s logging subsystem.
  16     /// </summary>
  17     public class LogConfig {
  18         /// <summary>
  19         /// If true, Berkeley DB will automatically remove log files that are no
  20         /// longer needed.
  21         /// </summary>
  22         /// <remarks>
  23         /// <para>
  24         /// Automatic log file removal is likely to make catastrophic recovery
  25         /// impossible.
  26         /// </para>
  27         /// <para>
  28         /// Replication Manager applications operate in a group-aware manner for
  29         /// log file removal, and automatic log file removal simplifies the
  30         /// application.
  31         /// </para>
  32         /// <para>
  33         /// Replication Base API applications will rarely want to configure
  34         /// automatic log file removal as it increases the likelihood a master
  35         /// will be unable to satisfy a client's request for a recent log
  36         /// record.
  37         /// </para>
  38         /// </remarks>
  39         public bool AutoRemove;
  40         /// <summary>
  41         /// If true, Berkeley DB will flush log writes to the backing disk
  42         /// before returning from the write system call, rather than flushing
  43         /// log writes explicitly in a separate system call, as necessary.
  44         /// </summary>
  45         /// <remarks>
  46         /// <para>
  47         /// This is only available on some systems (for example, systems
  48         /// supporting the IEEE/ANSI Std 1003.1 (POSIX) standard O_DSYNC flag,
  49         /// or systems supporting the Windows FILE_FLAG_WRITE_THROUGH flag).
  50         /// This flag may result in inaccurate file modification times and other
  51         /// file-level information for Berkeley DB log files. This flag may
  52         /// offer a performance increase on some systems and a performance
  53         /// decrease on others.
  54         /// </para>
  55         /// </remarks>
  56         public bool ForceSync;
  57         /// <summary>
  58         /// If true, maintain transaction logs in memory rather than on disk.
  59         /// </summary>
  60         /// <remarks>
  61         /// <para>
  62         /// This means that transactions exhibit the ACI (atomicity,
  63         /// consistency, and isolation) properties, but not D (durability); that
  64         /// is, database integrity will be maintained, but if the application or
  65         /// system fails, integrity will not persist. All database files must be
  66         /// verified and/or restored from a replication group master or archival
  67         /// backup after application or system failure.
  68         /// </para>
  69         /// <para>
  70         /// When in-memory logs are configured and no more log buffer space is
  71         /// available, Berkeley DB methods may throw
  72         /// <see cref="FullLogBufferException"/>. When choosing log buffer and
  73         /// file sizes for in-memory logs, applications should ensure the
  74         /// in-memory log buffer size is large enough that no transaction will
  75         /// ever span the entire buffer, and avoid a state where the in-memory
  76         /// buffer is full and no space can be freed because a transaction that
  77         /// started in the first log "file" is still active.
  78         /// </para>
  79         /// </remarks>
  80         public bool InMemory;
  81         /// <summary>
  82         /// If true, turn off system buffering of Berkeley DB log files to avoid
  83         /// double caching.
  84         /// </summary>
  85         public bool NoBuffer;
  86         /// <summary>
  87         /// If true, zero all pages of a log file when that log file is created.
  88         /// </summary>
  89         /// <remarks>
  90         /// <para>
  91         /// This has shown to provide greater transaction throughput in some
  92         /// environments. The log file will be zeroed by the thread which needs
  93         /// to re-create the new log file. Other threads may not write to the
  94         /// log file while this is happening.
  95         /// </para>
  96         /// </remarks>
  97         public bool ZeroOnCreate;
  98
  99         internal uint ConfigFlags {
 100             get {
 101                 uint ret = 0;
 102                 if (AutoRemove)
 103                     ret |= DbConstants.DB_LOG_AUTO_REMOVE;
 104                 if (ForceSync)
 105                     ret |= DbConstants.DB_LOG_DSYNC;
 106                 if (InMemory)
 107                     ret |= DbConstants.DB_LOG_IN_MEMORY;
 108                 if (NoBuffer)
 109                     ret |= DbConstants.DB_LOG_DIRECT;
 110                 if (ZeroOnCreate)
 111                     ret |= DbConstants.DB_LOG_ZERO;
 112                 return ret;
 113             }
 114         }
 115
 116         internal bool bsizeIsSet;
 117         private uint _bsize;
 118         /// <summary>
 119         /// The size of the in-memory log buffer, in bytes.
 120         /// </summary>
 121         /// <remarks>
 122         /// <para>
 123         /// When the logging subsystem is configured for on-disk logging, the
 124         /// default size of the in-memory log buffer is approximately 32KB. Log
 125         /// information is stored in-memory until the storage space fills up or
 126         /// transaction commit forces the information to be flushed to stable
 127         /// storage. In the presence of long-running transactions or
 128         /// transactions producing large amounts of data, larger buffer sizes
 129         /// can increase throughput.
 130         /// </para>
 131         /// <para>
 132         /// When the logging subsystem is configured for in-memory logging, the
 133         /// default size of the in-memory log buffer is 1MB. Log information is
 134         /// stored in-memory until the storage space fills up or transaction
 135         /// abort or commit frees up the memory for new transactions. In the
 136         /// presence of long-running transactions or transactions producing
 137         /// large amounts of data, the buffer size must be sufficient to hold
 138         /// all log information that can accumulate during the longest running
 139         /// transaction. When choosing log buffer and file sizes for in-memory
 140         /// logs, applications should ensure the in-memory log buffer size is
 141         /// large enough that no transaction will ever span the entire buffer,
 142         /// and avoid a state where the in-memory buffer is full and no space
 143         /// can be freed because a transaction that started in the first log
 144         /// "file" is still active.
 145         /// </para>
 146         /// <para>
 147         /// If the database environment already exists when
 148         /// <see cref="DatabaseEnvironment.Open"/> is called, the value of
 149         /// BufferSize will be ignored.
 150         /// </para>
 151         /// </remarks>
 152         public uint BufferSize {
 153             get { return _bsize; }
 154             set {
 155                 bsizeIsSet = true;
 156                 _bsize = value;
 157             }
 158         }
 159
 160         /// <summary>
 161         /// The path of a directory to be used as the location of logging files.
 162         /// Log files created by the Log Manager subsystem will be created in
 163         /// this directory.
 164         /// </summary>
 165         /// <remarks>
 166         /// <para>
 167         /// If no logging directory is specified, log files are created in the
 168         /// environment home directory. See Berkeley DB File Naming in the
 169         /// Programmer's Reference Guide for more information.
 170         /// </para>
 171         /// <para>
 172         /// For the greatest degree of recoverability from system or application
 173         /// failure, database files and log files should be located on separate
 174         /// physical devices.
 175         /// </para>
 176         /// <para>
 177         /// If the database environment already exists when
 178         /// <see cref="DatabaseEnvironment.Open"/> is called, the value of
 179         /// Dir must be consistent with the existing environment or corruption
 180         /// can occur.
 181         /// </para>
 182         /// </remarks>
 183         public string Dir;
 184
 185         private uint _initlogidcount;
 186         internal bool initLogIdCountIsSet;
 187         /// <summary>
 188         /// The initial number of log identifier entities created by the
 189         /// Berkeley DB environment
 190         /// </summary>
 191         /// <remarks>
 192         /// <para>
 193         /// This value is used by <see cref="DatabaseEnvironment.Open"/> to
 194         /// force Berkeley DB to allocate a certain number of log identifier
 195         /// objects when the environment is created. This can be useful if an
 196         /// application uses a large number of log identifier objects, and
 197         /// experiences performance issues with the default dynamic allocation
 198         /// algorithm.
 199         /// </para>
 200         /// <para>
 201         /// If the database environment already exists when
 202         /// <see cref="DatabaseEnvironment.Open"/> is called, the value of
 203         /// InitLogIds will be ignored.
 204         /// </para>
 205         /// </remarks>
 206         public uint InitLogIdCount {
 207             get { return _initlogidcount; }
 208             set {
 209                 initLogIdCountIsSet = true;
 210                 _initlogidcount = value;
 211             }
 212         }
 213
 214         internal bool modeIsSet;
 215         private int _mode;
 216         /// <summary>
 217         /// The absolute file mode for created log files.
 218         /// </summary>
 219         /// <remarks>
 220         /// <para>
 221         /// This method is only useful for the rare Berkeley DB application that
 222         /// does not control its umask value.
 223         /// </para>
 224         /// <para>
 225         /// Normally, if Berkeley DB applications set their umask appropriately,
 226         /// all processes in the application suite will have read permission on
 227         /// the log files created by any process in the application suite.
 228         /// However, if the Berkeley DB application is a library, a process
 229         /// using the library might set its umask to a value preventing other
 230         /// processes in the application suite from reading the log files it
 231         /// creates. In this rare case, the DB_ENV->set_lg_filemode() method can
 232         /// be used to set the mode of created log files to an absolute value.
 233         /// </para>
 234         /// </remarks>
 235         public int FileMode {
 236             get { return _mode; }
 237             set {
 238                 modeIsSet = true;
 239                 _mode = value;
 240             }
 241         }
 242
 243         internal bool maxSizeIsSet;
 244         private uint _maxSize;
 245         /// <summary>
 246         /// The maximum size of a single file in the log, in bytes. Because
 247         /// <see cref="LSN.Offset"/> is an unsigned four-byte value, MaxFileSize
 248         /// may not be larger than the maximum unsigned four-byte value.
 249         /// </summary>
 250         /// <remarks>
 251         /// <para>
 252         /// When the logging subsystem is configured for on-disk logging, the
 253         /// default size of a log file is 10MB.
 254         /// </para>
 255         /// <para>
 256         /// When the logging subsystem is configured for in-memory logging, the
 257         /// default size of a log file is 256KB. In addition, the
 258         /// <see cref="BufferSize">configured log buffer size</see> must be
 259         /// larger than the log file size. (The logging subsystem divides memory
 260         /// configured for in-memory log records into "files", as database
 261         /// environments configured for in-memory log records may exchange log
 262         /// records with other members of a replication group, and those members
 263         /// may be configured to store log records on-disk.) When choosing log
 264         /// buffer and file sizes for in-memory logs, applications should ensure
 265         /// the in-memory log buffer size is large enough that no transaction
 266         /// will ever span the entire buffer, and avoid a state where the
 267         /// in-memory buffer is full and no space can be freed because a
 268         /// transaction that started in the first log "file" is still active.
 269         /// </para>
 270         /// <para>
 271         /// See Log File Limits in the Programmer's Reference Guide for more
 272         /// information.
 273         /// </para>
 274         /// <para>
 275         /// If no size is specified by the application, the size last specified
 276         /// for the database region will be used, or if no database region
 277         /// previously existed, the default will be used.
 278         /// </para></remarks>
 279         public uint MaxFileSize {
 280             get { return _maxSize; }
 281             set {
 282                 maxSizeIsSet = true;
 283                 _maxSize = value;
 284             }
 285         }
 286
 287         internal bool regionSizeIsSet;
 288         private uint _regionSize;
 289         /// <summary>
 290         /// Te size of the underlying logging area of the Berkeley DB
 291         /// environment, in bytes.
 292         /// </summary>
 293         /// <remarks>
 294         /// <para>
 295         /// By default, or if the value is set to 0, the default size is
 296         /// approximately 60KB. The log region is used to store filenames, and
 297         /// so may need to be increased in size if a large number of files will
 298         /// be opened and registered with the specified Berkeley DB
 299         /// environment's log manager.
 300         /// </para>
 301         /// <para>
 302         /// If the database environment already exists when
 303         /// <see cref="DatabaseEnvironment.Open"/> is called, the value of
 304         /// RegionSize will be ignored.
 305         /// </para>
 306         /// </remarks>
 307         public uint RegionSize {
 308             get { return _regionSize; }
 309             set {
 310                 regionSizeIsSet = true;
 311                 _regionSize = value;
 312             }
 313         }
 314
 315
 316
 317     }
 318 }