DuplicateDateLogHandle

Overview

DuplicateDateLogHandle creates a new DATE_LOG_HANDLE that references the same shared context as the source handle. This enables multiple threads to independently query and cache the last accessed date item without mutex contention. Each duplicated handle maintains its own cache but shares the underlying date collection, providing thread-safe concurrent access with minimal lock contention.

Purpose

This function is essential for multi-threaded applications that need concurrent read access to the same date collection. Rather than forcing all threads to compete for a single handle's resources, DuplicateDateLogHandle allows each thread to have its own handle with independent caches while sharing the underlying date data.

Key Features

• Independent handle per thread reduces lock contention
• Shared underlying date collection saves memory
• Per-handle cached "last accessed" date for performance
• Reference counting manages shared context lifetime
• Optional file info duplication for file-based handles
• Automatic cleanup via FreeDateCollectionHandle()

Function Signature

                HRESULT  _Must_inspect_result_ _Success_(SUCCEEDED(return))DuplicateDateLogHandle(
                    _In_  DATE_LOG_HANDLE hSourceHandle,
                    _Out_ DATE_LOG_HANDLE * lpTargetHandle
                );
            

Calling Convention

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

Parameters

Return Values

Success

Duplicate handle created successfully. lpTargetHandle contains the new handle pointer.

Validation Errors

Source handle is invalid, corrupted, or being freed by another thread.

lpTargetHandle is NULL.

Resource Allocation Errors

Insufficient memory to allocate new DATE_LOG structure or mutex.

System error from mutex creation or file duplication. Wrapped as HRESULT.

Behavior and Operations

Duplication Process

1. Validate source handle is valid and accessible
2. Acquire source handle's mutex
3. Allocate new DATE_LOG structure
4. If file info attached: duplicate file info
5. Copy context pointer (shared, not duplicated)
6. Create independent mutex for new handle
7. Increment reference count on shared context
8. Release source handle's mutex
9. Return new independent handle

Shared vs. Independent Resources

Shared Between Original and Duplicate

• DATE_LOG_CORE (underlying date items array)
• Context state (magic number, allocated count)
• Reference counting mechanism
• Holidays handle (if present)

Independent Per Handle

• DATE_LOG handle structure itself
• Mutex for handle-level synchronization
• Cached last accessed date (hLastDate)
• Optional file info duplicate

Reference Counting

The duplication process increments the shared context's reference count:

• Initial handle: count = 1
• Each DuplicateDateLogHandle() call: count += 1
• Each FreeDateCollectionHandle() call: count -= 1
• When count reaches 0: context is freed

Usage Examples

                    // Main thread: create and load date log
                    DATE_LOG_HANDLE hMainDateLog = NULL;
                    InitializeDateLogHandle(NULL, 0, hHolidays, &hMainDateLog, HandleIsForDatelog);
                    LoadDateLogHandle(pFile, NULL, NULL, hMainDateLog, NULL, 0);

                    // Worker threads can now duplicate the handle
                    for (int i = 0; i < 4; i++) {
                        DATE_LOG_HANDLE hDuplicate = NULL;
                        if (SUCCEEDED(DuplicateDateLogHandle(hMainDateLog, &hDuplicate))) {
                             // Each thread gets its own independent handle
                             CreateThread(NULL, 0, WorkerThreadProc, hDuplicate, 0, NULL);
                        }
                    }

                    // Worker thread function
                    DWORD WINAPI WorkerThreadProc(LPVOID lpParam) {
                    DATE_LOG_HANDLE hDateLog = (DATE_LOG_HANDLE)lpParam;

                    // Query dates without contending with other threads
                    for (int i = 0; i < 1000; i++) {
                        DATE_ITEM_HANDLE hDate = FindDateItemByGuid(hDateLog, &dateId);
                    }

                    // Each thread frees its own handle
                    FreeDateCollectionHandle(hDateLog);
                    return 0;
                    

                    FreeDateCollectionHandle(hMainDateLog);
                

                    DATE_LOG_HANDLE hOriginal = /* valid handle */;
                    DATE_LOG_HANDLE hDuplicate = NULL;

                    HRESULT hr = DuplicateDateLogHandle(hOriginal, &hDuplicate);
                    if (hr == HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE)) {
                        printf("Source handle is invalid or being freed\n");
                    }
                    else if (hr == HRESULT_FROM_WIN32(ERROR_OUTOFMEMORY)) {
                         printf("Insufficient memory to create duplicate\n");
                    }
                    else if (SUCCEEDED(hr)) {
                        printf("Duplicate handle created successfully\n");
                        FreeDateCollectionHandle(hDuplicate);
                    }

                    FreeDateCollectionHandle(hOriginal);
               

Performance Considerations

Benefits

• Reduced Lock Contention: Each thread has independent cache
• Memory Efficient: Shared underlying collection avoids duplication
• Better Cache Locality: Per-thread last-accessed item cache
• Scalable: Performance improves with more concurrent threads

Scalability

• Without Duplication: All threads contend for single handle's mutex
• With Duplication: Only reference counting involves shared synchronization
• Recommendation: Use duplication for concurrent read-heavy workloads

Important Notes

Related Functions

• InitializeDateLogHandle() - Create initial date log handle
• FreeDateCollectionHandle() - Release handle and decrement reference count
• FindDateItemByGuid() - Query date items using duplicated handle
• GetDateCollectionLength() - Query collection size