/*-
* See the file LICENSE for redistribution information.
*
* Copyright (c) 2009 Oracle. All rights reserved.
*
*/
using System;
using System.Collections.Generic;
using System.Text;
using BerkeleyDB.Internal;
namespace BerkeleyDB {
/// <summary>
/// A class representing configuration parameters for a
/// <see cref="DatabaseEnvironment"/>'s logging subsystem.
/// </summary>
public class LogConfig {
/// <summary>
/// If true, Berkeley DB will automatically remove log files that are no
/// longer needed.
/// </summary>
/// <remarks>
/// <para>
/// Automatic log file removal is likely to make catastrophic recovery
/// impossible.
/// </para>
/// <para>
/// Replication applications will rarely want to configure automatic log
/// file removal as it increases the likelihood a master will be unable
/// to satisfy a client's request for a recent log record.
/// </para>
/// </remarks>
public bool AutoRemove;
/// <summary>
/// If true, Berkeley DB will flush log writes to the backing disk
/// before returning from the write system call, rather than flushing
/// log writes explicitly in a separate system call, as necessary.
/// </summary>
/// <remarks>
/// <para>
/// This is only available on some systems (for example, systems
/// supporting the IEEE/ANSI Std 1003.1 (POSIX) standard O_DSYNC flag,
/// or systems supporting the Windows FILE_FLAG_WRITE_THROUGH flag).
/// This flag may result in inaccurate file modification times and other
/// file-level information for Berkeley DB log files. This flag may
/// offer a performance increase on some systems and a performance
/// decrease on others.
/// </para>
/// </remarks>
public bool ForceSync;
/// <summary>
/// If true, maintain transaction logs in memory rather than on disk.
/// </summary>
/// <remarks>
/// <para>
/// This means that transactions exhibit the ACI (atomicity,
/// consistency, and isolation) properties, but not D (durability); that
/// is, database integrity will be maintained, but if the application or
/// system fails, integrity will not persist. All database files must be
/// verified and/or restored from a replication group master or archival
/// backup after application or system failure.
/// </para>
/// <para>
/// When in-memory logs are configured and no more log buffer space is
/// available, Berkeley DB methods may throw
/// <see cref="FullLogBufferException"/>. When choosing log buffer and
/// file sizes for in-memory logs, applications should ensure the
/// in-memory log buffer size is large enough that no transaction will
/// ever span the entire buffer, and avoid a state where the in-memory
/// buffer is full and no space can be freed because a transaction that
/// started in the first log "file" is still active.
/// </para>
/// </remarks>
public bool InMemory;
/// <summary>
/// If true, turn off system buffering of Berkeley DB log files to avoid
/// double caching.
/// </summary>
public bool NoBuffer;
/// <summary>
/// If true, zero all pages of a log file when that log file is created.
/// </summary>
/// <remarks>
/// <para>
/// This has shown to provide greater transaction throughput in some
/// environments. The log file will be zeroed by the thread which needs
/// to re-create the new log file. Other threads may not write to the
/// log file while this is happening.
/// </para>
/// </remarks>
public bool ZeroOnCreate;
internal uint ConfigFlags {
get {
uint ret = 0;
if (AutoRemove)
ret |= DbConstants.DB_LOG_AUTO_REMOVE;
if (ForceSync)
ret |= DbConstants.DB_LOG_DSYNC;
if (InMemory)
ret |= DbConstants.DB_LOG_IN_MEMORY;
if (NoBuffer)
ret |= DbConstants.DB_LOG_DIRECT;
if (ZeroOnCreate)
ret |= DbConstants.DB_LOG_ZERO;
return ret;
}
}
internal bool bsizeIsSet;
private uint _bsize;
/// <summary>
/// The size of the in-memory log buffer, in bytes.
/// </summary>
/// <remarks>
/// <para>
/// When the logging subsystem is configured for on-disk logging, the
/// default size of the in-memory log buffer is approximately 32KB. Log
/// information is stored in-memory until the storage space fills up or
/// transaction commit forces the information to be flushed to stable
/// storage. In the presence of long-running transactions or
/// transactions producing large amounts of data, larger buffer sizes
/// can increase throughput.
/// </para>
/// <para>
/// When the logging subsystem is configured for in-memory logging, the
/// default size of the in-memory log buffer is 1MB. Log information is
/// stored in-memory until the storage space fills up or transaction
/// abort or commit frees up the memory for new transactions. In the
/// presence of long-running transactions or transactions producing
/// large amounts of data, the buffer size must be sufficient to hold
/// all log information that can accumulate during the longest running
/// transaction. When choosing log buffer and file sizes for in-memory
/// logs, applications should ensure the in-memory log buffer size is
/// large enough that no transaction will ever span the entire buffer,
/// and avoid a state where the in-memory buffer is full and no space
/// can be freed because a transaction that started in the first log
/// "file" is still active.
/// </para>
/// <para>
/// If the database environment already exists when
/// <see cref="DatabaseEnvironment.Open"/> is called, the value of
/// BufferSize will be ignored.
/// </para>
/// </remarks>
public uint BufferSize {
get { return _bsize; }
set {
bsizeIsSet = true;
_bsize = value;
}
}
/// <summary>
/// The path of a directory to be used as the location of logging files.
/// Log files created by the Log Manager subsystem will be created in
/// this directory.
/// </summary>
/// <remarks>
/// <para>
/// If no logging directory is specified, log files are created in the
/// environment home directory. See Berkeley DB File Naming in the
/// Programmer's Reference Guide for more information.
/// </para>
/// <para>
/// For the greatest degree of recoverability from system or application
/// failure, database files and log files should be located on separate
/// physical devices.
/// </para>
/// <para>
/// If the database environment already exists when
/// <see cref="DatabaseEnvironment.Open"/> is called, the value of
/// Dir must be consistent with the existing environment or corruption
/// can occur.
/// </para>
/// </remarks>
public string Dir;
internal bool modeIsSet;
private int _mode;
/// <summary>
/// The absolute file mode for created log files.
/// </summary>
/// <remarks>
/// <para>
/// This method is only useful for the rare Berkeley DB application that
/// does not control its umask value.
/// </para>
/// <para>
/// Normally, if Berkeley DB applications set their umask appropriately,
/// all processes in the application suite will have read permission on
/// the log files created by any process in the application suite.
/// However, if the Berkeley DB application is a library, a process
/// using the library might set its umask to a value preventing other
/// processes in the application suite from reading the log files it
/// creates. In this rare case, the DB_ENV->set_lg_filemode() method can
/// be used to set the mode of created log files to an absolute value.
/// </para>
/// </remarks>
public int FileMode {
get { return _mode; }
set {
modeIsSet = true;
_mode = value;
}
}
internal bool maxSizeIsSet;
private uint _maxSize;
/// <summary>
/// The maximum size of a single file in the log, in bytes. Because
/// <see cref="LSN.Offset"/> is an unsigned four-byte value, MaxFileSize
/// may not be larger than the maximum unsigned four-byte value.
/// </summary>
/// <remarks>
/// <para>
/// When the logging subsystem is configured for on-disk logging, the
/// default size of a log file is 10MB.
/// </para>
/// <para>
/// When the logging subsystem is configured for in-memory logging, the
/// default size of a log file is 256KB. In addition, the
/// <see cref="BufferSize">configured log buffer size</see> must be
/// larger than the log file size. (The logging subsystem divides memory
/// configured for in-memory log records into "files", as database
/// environments configured for in-memory log records may exchange log
/// records with other members of a replication group, and those members
/// may be configured to store log records on-disk.) When choosing log
/// buffer and file sizes for in-memory logs, applications should ensure
/// the in-memory log buffer size is large enough that no transaction
/// will ever span the entire buffer, and avoid a state where the
/// in-memory buffer is full and no space can be freed because a
/// transaction that started in the first log "file" is still active.
/// </para>
/// <para>
/// See Log File Limits in the Programmer's Reference Guide for more
/// information.
/// </para>
/// <para>
/// If no size is specified by the application, the size last specified
/// for the database region will be used, or if no database region
/// previously existed, the default will be used.
/// </para></remarks>
public uint MaxFileSize {
get { return _maxSize; }
set {
maxSizeIsSet = true;
_maxSize = value;
}
}
internal bool regionSizeIsSet;
private uint _regionSize;
/// <summary>
/// Te size of the underlying logging area of the Berkeley DB
/// environment, in bytes.
/// </summary>
/// <remarks>
/// <para>
/// By default, or if the value is set to 0, the default size is
/// approximately 60KB. The log region is used to store filenames, and
/// so may need to be increased in size if a large number of files will
/// be opened and registered with the specified Berkeley DB
/// environment's log manager.
/// </para>
/// <para>
/// If the database environment already exists when
/// <see cref="DatabaseEnvironment.Open"/> is called, the value of
/// RegionSize will be ignored.
/// </para>
/// </remarks>
public uint RegionSize {
get { return _regionSize; }
set {
regionSizeIsSet = true;
_regionSize = value;
}
}
}
}