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