ConvertToDateLogHandle

Overview

ConvertToDateLogHandle verifies and converts a DATE_RANGE_HANDLE back to a DATE_LOG_HANDLE by performing comprehensive validation of the backing file and its contents. This function is typically called as the final step of a merge operation to ensure data integrity before the handle is ready for production use.

Purpose

After merging date ranges into a date log using MergeDateLogHandle(), the destination handle remains in the "range" state (with magic __RANGE_LOG_MAGIC__) until this function successfully converts it to the "log" state (__DATE_LOG_MAGIC__). The conversion involves:

• Creating a temporary date log handle for isolated verification
• Re-parsing the backing file to validate its integrity
• Verifying that expected date items exist in the re-parsed data
• Updating the magic number only if all verifications succeed

Key Features

• Two-level mutex protection (handle and context mutexes)
• Isolated verification using temporary handles
• Atomic state transitions with magic number updates
• Graceful failure with preserved original state if verification fails
• Proper error recovery with cleanup of temporary resources

Function Signature

HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return)) ConvertToDateLogHandle(
    _Inout_ _Pre_valid_ DATE_RANGE_HANDLE hDateRangeHandle,
    _In_opt_ DATE_ITEM_HANDLE hLastDate
);

Calling Convention

Standard C calling convention with SAL annotations indicating the function requires result inspection and modifies the handle in-place on success.

Parameters

Return Values

Success Cases

The DATE_RANGE_HANDLE was successfully converted to a DATE_LOG_HANDLE. The magic number has been updated to __DATE_LOG_MAGIC__ and the handle is now ready for use as a date log. All verification checks passed, including the optional last date verification if hLastDate was provided.

Error Cases

Validation and Pre-condition Errors

The provided handle is not a valid DATE_RANGE_HANDLE or the file information is invalid. The handle magic number is incorrect for this operation.

Multiple failure scenarios:

• The handle's context, core, or file information is invalid
• The last date verification failed (provided hLastDate not found in re-parsed data)
• Context or handle guard checks failed
• Mutex acquisition failed
• Temporary handle creation failed

Synchronization Errors

System error from mutex acquisition. May indicate deadlock or resource exhaustion.

File Parsing Errors

See return codes from ParseDateLogFiles() and InitializeDateLogHandle() including:

Return Value Checking

// Recommended error checking pattern
HRESULT hr = ConvertToDateLogHandle(hDateRange, hLastDate);

if (SUCCEEDED(hr)) {
    // Conversion successful - handle is now a DATE_LOG_HANDLE
    printf("Range successfully converted to log\n");
    // Now safe to use as DATE_LOG_HANDLE
} else if (hr == HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE)) {
    // Last date verification failed or handle invalid
    printf("Conversion failed: handle or date verification failed\n");
    // Handle remains as DATE_RANGE_HANDLE
} else {
    // Other error - investigate
    printf("Conversion failed: 0x%08X\n", hr);
}

Behavior and Operations

Execution Flow

Validation Phase

1. Verify input DATE_RANGE_HANDLE is valid via IsValidDateRangeHandle()
2. Guard the context pointer (must not be NULL)
3. Guard the core pointer (must not be NULL)
4. Verify file information is valid via IsValidFileInfo()

Lock Acquisition Phase

Acquires two mutexes in this order:

1. Handle Mutex: pDateLog->hMutex with INFINITE timeout
2. Context Mutex: pDateLog->pContext->hMutex with INFINITE timeout

Verification Phase (Inside Lock Protection)

1. Create temporary DATE_LOG_HANDLE using InitializeDateLogHandle() with same configuration
2. Re-parse backing file via ParseDateLogFiles() with PARSE_VERIFY_ENABLE_FLAG
3. If hLastDate provided, search for it in re-parsed data using SearchDateItem()
4. If date not found, return ERROR_INVALID_HANDLE (verification failed)

State Update Phase (Atomic)

1. Only if all verifications succeeded, update: pDateLog->pContext->dwMagic = __DATE_LOG_MAGIC__
2. This is the atomic transition point from range to log state

Cleanup Phase

1. Clean up temporary DATE_LOG_HANDLE via CloseDateLogHandle()
2. If cleanup fails but main operation succeeded, preserve success
3. If cleanup fails after main operation already failed, preserve original error
4. Release context mutex (in __finally block)
5. Release handle mutex (in __finally block)

Synchronization and Thread Safety

Lock Protection Strategy

The function uses structured exception handling (__try/__finally) to ensure mutexes are released even if verification fails:

BOOL bHandleMutex = FALSE;
BOOL bContextMutex = FALSE;

// Acquire handle mutex first
dwWaitResult = WaitForSingleObject(pDateLog->hMutex, INFINITE);
if (dwWaitResult != WAIT_OBJECT_0) {
    return HRESULT_FROM_WIN32(GetLastError());
}
bHandleMutex = TRUE;

__try {
    // Acquire context mutex
    dwWaitResult = WaitForSingleObject(pDateLog->pContext->hMutex, INFINITE);
    if (dwWaitResult != WAIT_OBJECT_0) {
        hr = HRESULT_FROM_WIN32(GetLastError());
        __leave;
    }
    bContextMutex = TRUE;
    
    // ... perform verification ...
    
} __finally {
    // Always release in reverse order
    if (bContextMutex) {
        ReleaseMutex(pDateLog->pContext->hMutex);
    }
    if (bHandleMutex) {
        ReleaseMutex(pDateLog->hMutex);
    }
}

Deadlock Prevention

Isolated Verification

The temporary handle created during verification is completely isolated from the original range handle:

• Separate DATE_LOG structure (not the original)
• Shares the same context configuration but creates new core array
• File re-parsing creates fresh date items
• If verification fails, original range handle state is unchanged
• Temporary handle is cleaned up regardless of verification result

Examples

Post-Merge Conversion

// Merge source range into destination log
DATE_LOG_HANDLE hDestLog = NULL;
DATE_RANGE_HANDLE hSourceRange = NULL;

// ... initialize and populate handles ...

// Perform merge operation
HRESULT hr = MergeDateLogHandle(
    hDestLog,
    hSourceRange,
    DATE_RANGE_MERGE_FAVOR_DEST
);

if (SUCCEEDED(hr)) {
    // After merge, destination is still in RANGE state
    // Get the last date to verify
    DATE_ITEM_HANDLE hLastDate = GetDateLogLastDate(hDestLog);
    
    // Convert to LOG state with verification
    hr = ConvertToDateLogHandle(
        (DATE_RANGE_HANDLE)hDestLog,
        hLastDate
    );
    
    if (SUCCEEDED(hr)) {
        // Now safe to use as DATE_LOG_HANDLE for database insertion
        printf("Merge complete and verified\n");
    } else {
        printf("Verification failed, data integrity issue\n");
    }
    
    if (hLastDate) {
        FreeDateItem(hLastDate);
    }
}

Verification Without Specific Date

// Convert range to log without verifying a specific date
// This skips the SearchDateItem verification step

HRESULT hr = ConvertToDateLogHandle(
    hDateRange,
    NULL  // No specific date to verify
);

if (SUCCEEDED(hr)) {
    // File was re-parsed successfully
    // Range is now converted to LOG state
} else {
    // File parsing failed
    // Range remains unconverted
}

Error Handling and Retry

DATE_RANGE_HANDLE hRange = NULL;
HRESULT hr = S_OK;
int retryCount = 0;
const int MAX_RETRIES = 3;

while (retryCount < MAX_RETRIES) {
    DATE_ITEM_HANDLE hLastDate = GetDateLogLastDate(hRange);
    
    hr = ConvertToDateLogHandle(hRange, hLastDate);
    
    if (SUCCEEDED(hr)) {
        printf("Conversion successful on attempt %d\n", retryCount + 1);
        break;
    }
    
    if (hLastDate) {
        FreeDateItem(hLastDate);
    }
    
    retryCount++;
    if (retryCount < MAX_RETRIES) {
        printf("Conversion failed, retrying (%d/%d)...\n", retryCount, MAX_RETRIES);
        Sleep(100);  // Brief delay before retry
    }
}

if (FAILED(hr)) {
    printf("Conversion failed after %d attempts\n", MAX_RETRIES);
}

Notes and Important Information

Magic Number Semantics

File Integrity

The re-parsing of the backing file serves two purposes:

• Integrity Verification: Confirms that file corruption did not occur during merge
• Date Item Verification: Ensures all expected date items were successfully written

Temporary Handle Cleanup

The temporary handle created during verification is automatically cleaned up via CloseDateLogHandle(). If cleanup fails:

• If main operation succeeded, the cleanup error replaces the success
• If main operation failed, the original error is preserved
• This ensures the most critical error is reported to the caller

When to Use Last Date Parameter

Provide the hLastDate parameter in these scenarios:

• When the caller knows the last date that was added and wants to verify it exists
• When data integrity is critical and extra verification is acceptable
• When debugging merge operation failures

Set hLastDate to NULL when:

• Performance is critical and date verification is not needed
• The file itself is trusted and only needs re-parsing for state verification

State Transitions