ILog interface (txlogpub.h)

Article
10/05/2021

Provides generic low-level logging functionality.

The Common Log File System (CLFS), provides functionality that is a superset of that provided by ILog.

Inheritance

The ILog interface inherits from the IUnknown interface. ILog also has these types of members:

Methods

The ILog interface has these methods.


ILog::AppendRecord Write a new record to the end of the log.
ILog::Force Forces the contents of the log to disk, at least up through the specified LSN.
ILog::GetLogLimits Retrieves information about the current bounds of the log.
ILog::ReadRecord Read a record from the log.
ILog::ReadRecordPrefix Reads an initial part of a record from the log.
ILog::SetAccessPolicyHint Provides a hint to the implementation about the pattern in which records will be read.
ILog::TruncatePrefix Throws away the specified prefix of the log, making it no longer retrievable.

Remarks

WAL is a technique used by certain applications, such as database management systems, to implement atomic and isolated transactions. This technique involves writing records of changes to the application's resources to a log before you make these changes. This way the changes can be reverted if they are required, for example if the transaction fails or is interrupted. In order for applications to provide transactions that are robust against interruptions such as system crash or power failure, the logging implementation must provide a method for forcing the log; that is, to make sure that previously written records are on disk before continuing.

Writing records that use ILog is a sequential operation; that is, new records are always appended to the end of the log. Each record appended to the log is assigned a log sequence number (LSN), a numeric identifier which may be used to retrieve the record later. The data type LSN is a typedef for LARGE_INTEGER, a signed 64-bit value; however, ILog uses only LSNs with nonnegative values. In addition, LSNs must satisfy the following conditions:

LSNs are monotonically increasing; if record B is written to the log after record A, the LSN of record B must be larger than the LSN of record A.
Values of zero and MAXLSN (0x7FFFFFFFFFFFFFFF) must never be used as the LSN of a record, as they have special meaning to some of the methods of ILog.

Other than the conditions here, no assumptions should be made about how LSNs are assigned by an implementation of ILog. In particular, it is not safe to assume that records will be assigned sequential values for LSNs.

After a record is appended to the log, it may not be modified. However, when previously written records are no longer needed, for example records of changes in a transaction that has already been committed, ILog supports truncating the log. This way, disk space that was used for nonessential records may be reused. Truncating the log consists of deleting all records with an LSN less than a specified value.

As a performance optimization, some implementations of ILog may buffer records in memory until the log is forced. If this is the case, special you must consider error control and recovery. Consider the following situation:

Record A is appended to the log, but the log is not forced. The ILog implementation copies the record to a buffer in memory and returns a success code.
Record B is appended to the log, and the ILog implementation decides to force the log to disk. This is either because the caller asked the log to be forced or because the memory buffer is full. However, the write operation fails, for example because of low disk space.

In this situation, it would be inappropriate for the ILog implementation to enable additional records to be appended to the log, unless it can guarantee that all records for which it returned a success code are first written to disk. One possible method of error control would be to pin the log in an error state when this situation occurs, permanently disallowing additional writes to the log instance. Callers that do not force the log to disk for each appended record should realize that this situation may occur and be able to handle it appropriately.

ILog File-based Implementation

The Windows operating system provides a file-based implementation of ILog, which enables you to create a log suited for write-ahead logging on a file. The log uses a file as a circular buffer, which enables unused space to be reused. This may also increase the size of the file that may be needed to fit additional records when the log is full. Changes to the log are made atomically, so that the contents of the log may be recovered after a crash. This implementation uses a buffer in memory for appending log records. As a result, records are not guaranteed to be written to disk when the ILog::AppendRecord method returns, unless the caller requests that the log be forced.

Use the following CLSID to create an instance of a file based log (see CoCreateInstance):

CLSID_SimpleFileBasedLog ({E16C0593-128F-11D1-97E4-00C04FB9618A} ).

The file based implementation of ILog additionally supports the IFileBasedLogInit and IPersistFile interfaces. Use IFileBasedLogInit::InitNew to create a new log file. Use IPersistFile::Load to open an existing log file.

This implementation uses a simple error control policy. If any one of the methods fails because of an error on the file-system level, which includes a disk full error, the log is pinned in an error state. This prevents clients from appending additional records to the file or reading potentially bad records. To continue to use the log file, you must create a new instance of the log.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	txlogpub.h