CloseDateLogHandle

Overview

CloseDateLogHandle closes and releases all resources associated with a DATE_LOG_HANDLE, including file information, synchronization objects, and shared context when all references are released. This function implements a reference-counted lifecycle pattern where the shared context is freed only when all active handles pointing to it have been closed.

Purpose

This function is the primary cleanup mechanism for date log handles. It handles:

• Decrementing the reference count for the shared context
• Freeing the shared context when the reference count reaches zero
• Releasing all file information resources
• Closing handle-level synchronization objects
• Freeing the handle structure itself

Key Features

• Returns HRESULT for comprehensive error reporting
• Thread-safe reference counting with critical sections
• Graceful failure handling with mutex timeout protection
• Proper resource cleanup order to prevent leaks
• Support for cascading handle closures in multithreaded scenarios

Function Signature

HRESULT _Success_(SUCCEEDED(return)) CloseDateLogHandle(
    _In_ _Post_invalid_ DATE_LOG_HANDLE hDateLogHandle
);

Calling Convention

Standard C calling convention with SAL annotations indicating successful return code expectation and handle invalidation after the call.

Parameters

Return Values

Success Cases

The handle was closed successfully and all resources were released. Reference count was decremented, and if it reached zero, the shared context and its resources were freed.

Error Cases

Validation and Synchronization Errors

The handle is invalid, NULL, or failed validation. Additionally, this error is returned if mutex acquisition fails, indicating either:

• Handle pointer is NULL
• Handle magic number does not match any valid type
• Context pointer is corrupted
• Mutex acquisition returned error status

System error from synchronization primitives. The handle state may be partially cleaned up.

Return Value Checking

// Recommended error checking pattern
DATE_LOG_HANDLE hDateLog = NULL;

// ... use the handle ...

HRESULT hr = CloseDateLogHandle(hDateLog);
if (SUCCEEDED(hr)) {
    printf("Handle closed successfully\n");
    hDateLog = NULL;  // Mark as invalid
} else if (hr == HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE)) {
    printf("Handle was already invalid or corrupted\n");
} else {
    printf("Close operation failed: 0x%08X\n", hr);
    // Do not attempt to use hDateLog further
}

Behavior and Operations

Execution Flow

Step-by-Step Process

1. Handle Validation: Calls IsValidDateLogHandle() to verify the handle structure and magic numbers
2. Extract Context: Retrieves pointers to the DATE_LOG and DATE_CONTEXT structures
3. Acquire Handle Mutex: Acquires pDateLog->hMutex with INFINITE timeout
4. Enter Critical Section: Increments lInsideCount and enters critical_section
5. Decrement Counter: Decrements pContext->uiHandles and saves the result
6. Leave Critical Section: Leaves critical section and decrements lInsideCount
7. Conditional Context Cleanup: If uiHandles == 0, calls FreeDateLogHandleContext()
8. Release Mutex: Releases pDateLog->hMutex
9. File Info Cleanup: If pDateLog->pFileInfo exists, calls FreeFileInfo()
10. Handle Mutex Cleanup: Closes pDateLog->hMutex
11. Handle Deallocation: Frees the DATE_LOG structure itself

Reference Counting Mechanism

The function uses a reference counting pattern where:

• Each handle holds a reference to a shared context
• The context tracks the number of active handles via uiHandles
• When the last handle is closed, the context is freed
• This allows multiple threads to safely access the same date collection through different handles

Context Cleanup

When FreeDateLogHandleContext() is called (i.e., when reference count reaches zero), it:

• Waits for all threads to exit critical sections (lInsideCount == 0)
• Frees the date item core array
• Closes the holidays handle if present
• Deletes the critical section
• Closes the context mutex
• Frees the context structure

Reference Counting Details

Lifecycle Example

// Initial creation - reference count = 1
DATE_LOG_HANDLE hLog1 = NULL;
InitializeDateLogHandle(..., &hLog1, ...);
// Internal: pContext->uiHandles = 1

// First duplication - reference count = 2
DATE_LOG_HANDLE hLog2 = NULL;
DuplicateDateLogHandle(hLog1, &hLog2);
// Internal: pContext->uiHandles = 2

// Close first handle - reference count = 1
CloseDateLogHandle(hLog1);  // Returns S_OK, context NOT freed
hLog1 = NULL;
// Internal: pContext->uiHandles = 1

// Close second handle - reference count = 0
CloseDateLogHandle(hLog2);  // Returns S_OK, context IS freed
hLog2 = NULL;
// Internal: context and all resources freed

Critical Sections and Interlocked Operations

Examples

Basic Usage

// Create a date log handle
DATE_LOG_HANDLE hDateLog = NULL;
HRESULT hr = InitializeDateLogHandle(
    NULL,                    // Security attributes
    DATE_LOG_MAX,            // Max size
    hHolidays,              // Holidays handle
    &hDateLog,              // Output
    HandleIsForDatelog      // Type
);

if (SUCCEEDED(hr)) {
    // Use the handle
    LoadDateLogHandle(..., hDateLog, ...);
    
    // Get some data
    DATE_ITEM_HANDLE hFirstDate = GetDateLogFirstDate(hDateLog);
    
    // When done, close it
    hr = CloseDateLogHandle(hDateLog);
    if (SUCCEEDED(hr)) {
        hDateLog = NULL;  // Mark invalid
    }
}

Multithreaded Usage

    // Main thread creates original handle
    DATE_LOG_HANDLE hOriginal = NULL;
    InitializeDateLogHandle(..., &hOriginal, ...);

    // Worker threads duplicate for concurrent access
    DWORD WINAPI WorkerThread(LPVOID lpParam) {
        DATE_LOG_HANDLE hWorker = NULL;
    
        // Duplicate handle for thread-local use
        HRESULT hr = DuplicateDateLogHandle(hOriginal, &hWorker);
        if (SUCCEEDED(hr)) {
            // Each thread can independently query dates
            DATE_ITEM_HANDLE hDate = FindDateItemByGuid(hWorker, &guid);
        
            // Clean up when done
            CloseDateLogHandle(hWorker);
        }
        return 0;
    }
                   

    // After all worker threads complete
    CloseDateLogHandle(hOriginal);
    hOriginal = NULL;  // All resources freed
                 

Error Handling

DATE_LOG_HANDLE hDateLog = NULL;

    // Initialize handle
    HRESULT hr = InitializeDateLogHandle(..., &hDateLog, ...);
    if (FAILED(hr)) {
        printf("Failed to create handle: 0x%08X\n", hr);
        return hr;
    }

    // Use handle...
    __try {
        // Perform operations on hDateLog
        hr = LoadDateLogHandle(..., hDateLog, ...);
        if (FAILED(hr)) {
            printf("Failed to load data: 0x%08X\n", hr);
        }
    } __finally {
        // Ensure proper cleanup even on exception
        if (hDateLog) {
            HRESULT hrClose = CloseDateLogHandle(hDateLog);
            if (FAILED(hrClose)) {
                printf("Warning: Close failed with 0x%08X\n", hrClose);
            }
            hDateLog = NULL;
        }
    }                     
    

Notes and Important Information

Handle Invalidation

Mutex Acquisition

The function acquires mutexes with INFINITE timeout. In extreme resource contention scenarios, this could cause thread blocking. However, this is preferred over timing out to ensure proper resource cleanup.

Cascading Cleanup

When the last handle is closed and the context is freed:

• If the context owns a holidays handle, that handle is also closed recursively
• All date items in the core array are freed
• The core mutex is closed
• The context critical section is deleted

File Information Cleanup

Each handle can have associated file information (for merge operations). This is freed separately from the context, ensuring:

• File handles are closed properly
• Temporary files are cleaned up
• Memory allocated for file metadata is freed

Performance Considerations

• Handle closure is O(1) in the common case (not the last handle)
• Last handle closure is O(n) where n is the number of date items (due to array cleanup)
• In multithreaded scenarios with many active handles, closure is fast as the context is not freed