MergeDateLogHandle

Overview

MergeDateLogHandle merges a source date range into a destination date log, with support for conflict resolution based on specified flags. This is a high-level wrapper that manages synchronization, file I/O, and recovery operations for date log merge operations.

Purpose

This function enables consolidation of multiple date logs or date ranges into a single authoritative date log. It supports two merge strategies:

• Favor Destination: Keep destination GUIDs when dates overlap
• Favor Source: Replace destination GUIDs with source values when dates overlap

Key Features

• Thread-safe merge with deadlock prevention via consistent lock ordering
• Automatic file I/O handling with region locking
• Backup and recovery support for failed merges
• Timeout-based synchronization (30-second default) to prevent indefinite hangs
• Atomic merge operations with rollback capability

Function Signature

            HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return)) MergeDateLogHandle(
                    _Inout_ _Pre_valid_  DATE_LOG_HANDLE hDestDateLog,
                    _In_  __readonly _Pre_valid_  DATE_RANGE_HANDLE hSourceDateLog,
                    _In_ DWORD dwFlags
            );
            

Calling Convention

Standard C calling convention with SAL annotations for parameter validation and return value inspection.

Parameters

Return Values

Success Cases

Merge operation completed successfully. Destination date log has been updated with merged data.

Error Cases

Validation Errors

Either destination or source handle is invalid, not a date log/range, or context is NULL.

Flags parameter is invalid. Neither DATE_RANGE_MERGE_FAVOR_DEST nor DATE_RANGE_MERGE_FAVOR_SOURCE was specified.

Synchronization Errors

Failed to acquire required mutex locks within 30-second timeout. Indicates another operation is holding locks or system is under resource contention.

Generic synchronization error from mutex or lock acquisition failure.

Memory and Resource Errors

Failed to allocate memory for merge context or backup structures.

Merge lock context allocation failed or internal handle validation failed.

Merge Operation Errors

See return codes from MergeDateLogCores() including:

File I/O Errors

Array or file restoration failed after merge failure. Destination context may be invalid.

File region could not be restored from backup after failed merge.

Return Value Checking

            // Recommended error checking pattern
            HRESULT hr = MergeDateLogHandle(
                hDestLog, 
                hSourceLog, 
                DATE_RANGE_MERGE_FAVOR_SOURCE | DATE_RANGE_MERGE_RESTORE_ON_FAILURE
            );

            if (SUCCEEDED(hr)) {
                // Merge completed successfully
                printf("Merge successful\n");
            } else if (hr == ERR_DATE_LOG_PENDING_IO) {
                // Retry operation after delay
                printf("Merge in progress, retry later\n");
            } else {
                // Log error and handle gracefully
                printf("Merge failed: 0x%08X\n", hr);
            }

Behavior and Operations

Execution Flow

Lock Acquisition Strategy

The function uses consistent lock ordering to prevent deadlocks:

1. Destination range mutex (30s timeout)
2. Source range mutex (30s timeout)
3. Destination context mutex (30s timeout)
4. Source context mutex (30s timeout)

Merge Process

Once all locks are acquired:

1. Allocate MERGE_LOCK_CONTEXT for tracking merge state
2. Invoke MergeDateLogCores() to perform in-memory merge
3. Update context state: set bHasChanged = TRUE
4. If file info present: duplicate file handle and lock regions
5. Update destination file with merged data via MergeDateLogFileInfo()
6. Unlock file regions and clean up resources

File I/O Handling

If destination has associated file info (pDateRangeDest->pFileInfo is not NULL):

• Duplicate file handle for safe concurrent I/O operations
• Lock affected file regions to prevent concurrent access
• Write merged date items to file at appropriate offsets
• Verify written bytes match expected count
• Always unlock regions before releasing locks

Recovery on Failure

If DATE_RANGE_MERGE_RESTORE_ON_FAILURE flag is set and merge/file update fails:

• Check if array backup was successfully created
• Restore in-memory date item array to original state
• If file was modified, restore file regions from backup
• Mark context as invalid if restoration fails

Resource Cleanup

In the __finally block:

• Unlock