GetDateCollectionLength

Overview

GetDateCollectionLength returns the current count of date items stored in a date collection handle. This function provides thread-safe access to the collection's length by acquiring the internal mutex and reading the length field.

Purpose

Get the actual number of date items currently in a collection. This is useful for:

• Determining the number of market dates in a collection
• Verifying collection state after merge or load operations
• Implementing validation logic based on collection size
• Allocating buffers or arrays for processing

Key Features

• Thread-safe implementation with 5-second mutex timeout
• Lightweight operation with minimal CPU overhead
• Returns sentinel value (0x00845698) on error for easy detection
• Works with all collection types: DateLog, DateRange, and Holidays
• No side effects on the collection state

Function Signature

DWORD _Check_return_ _On_failure_(return > DATE_LOG_MAX) GetDateCollectionLength(
    _In_ DATE_COLLECTION_HANDLE hDateCollection
);
            

Calling Convention

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

SAL Annotations

_Check_return_ : Caller must check the return value; ignoring it may lead to processing invalid data
_On_failure_(return > DATE_LOG_MAX) : On failure, return value will exceed DATE_LOG_MAX (0x00000000 to 0x001388 range)
                

Parameters

Return Values

Success Case

Returns the actual number of date items in the collection. Range is 0 (empty collection) through DATE_LOG_MAX (5000 items maximum). A value of 0 indicates an empty collection, which is valid.

Error Case

Indicates an error occurred. Possible error conditions:

• Handle is NULL or invalid
• Handle validation failed (magic number mismatch)
• Context is NULL or invalid
• Core date log is NULL or invalid
• Failed to acquire mutex within 5-second timeout
• Mutex wait returned an error state

Return Value Semantics

Checking Return Values

// Pattern 1: Simple validity check
DWORD dwLength = GetDateCollectionLength(hCollection);
if (dwLength == DATE_LOG_SENTINEL) {
    // Error occurred
    printf("Failed to get collection length\n");
    // Close handle and retry
} else if (dwLength == 0) {
    // Empty collection (valid)
    printf("Collection is empty\n");
} else {
    // Valid collection with dwLength items
    printf("Collection has %u items\n", dwLength);
}

// Pattern 2: Loop processing
DWORD dwMaxLen = GetDateCollectionMaximumLength(hCollection);
DWORD dwLen = GetDateCollectionLength(hCollection);
if (dwLen != DATE_LOG_SENTINEL && dwMaxLen != DATE_LOG_SENTINEL) {
    printf("Utilization: %u of %u (%.1f%%)\n", 
        dwLen, dwMaxLen, (100.0 * dwLen) / dwMaxLen);
}
            

Behavior and Operations

Execution Flow

Step-by-Step Operation

1. Handle Validation:
   Calls IsValidDateLogHandle(hDateCollection) to verify:
   • Handle pointer is not NULL
   • Handle magic number is valid (not marked invalid)
   • Handle context is not NULL
   • Handle type matches expected enum value
2. Early Exit on Invalid Handle:
   If validation fails, immediately returns DATE_LOG_SENTINEL
3. Context Extraction:
   Casts handle to PDATE_LOG and retrieves the core handle from pContext->hDateLogCore
4. Delegate to Core Getter:
   Calls GetDateLogCoreLength() which:
   • Re-validates the core pointer
   • Acquires the core's mutex with 5-second timeout
   • Reads the dwLength field inside the mutex
   • Releases the mutex
5. Return Result:
   Returns the length value or DATE_LOG_SENTINEL if any step fails

Thread Safety

The function is fully thread-safe:

• Mutex Protection: The core's length field is accessed under mutex lock
• Timeout: 5-second timeout prevents indefinite blocking
• No Side Effects: Read-only operation; does not modify collection state
• Lock Ordering: Single lock acquisition prevents deadlock

Error Handling Flow

// Error conditions handled gracefully
if (IsValidDateLogHandle(hDateCollection) == FALSE)
    return DATE_LOG_SENTINEL;  // Handle is invalid

PDATE_LOG pDateLog = (PDATE_LOG)hDateCollection;
return GetDateLogCoreLength(pDateLog->pContext->hDateLogCore);

// GetDateLogCoreLength also checks:
// - IsValidDateLogCore(hDateLogCore) 
// - Mutex timeout
// - Mutex wait result
            

Usage Examples

#include "datelog.h"

DWORD dwLength = GetDateCollectionLength(hMyCollection);

if (dwLength == DATE_LOG_SENTINEL) {
    printf("ERROR: Failed to get collection length\n");
    goto error_cleanup;
}

if (dwLength == 0) {
    printf("Collection is empty\n");
} else {
    printf("Collection contains %u market dates\n", dwLength);
}

// ... continue processing ...

error_cleanup:
    CloseDateLogHandle(hMyCollection);
    return FALSE;
                

// After merging two collections
HRESULT hr = MergeDateLogHandle(hDestLog, hSourceLog, 
                                DATE_RANGE_MERGE_FAVOR_SOURCE);

if (SUCCEEDED(hr)) {
    DWORD dwNewLength = GetDateCollectionLength(hDestLog);
    DWORD dwMaxLength = GetDateCollectionMaximumLength(hDestLog);
    
    if (dwNewLength != DATE_LOG_SENTINEL && 
        dwMaxLength != DATE_LOG_SENTINEL) {
        
        printf("Merge successful. Collection now has %u dates\n", dwNewLength);
        printf("Capacity utilization: %.1f%%\n", 
            (100.0 * dwNewLength) / dwMaxLength);
        
        // Verify merge didn't exceed capacity
        if (dwNewLength > dwMaxLength) {
            printf("ERROR: Length exceeds maximum!\n");
        }
    } else {
        printf("ERROR: Failed to verify merged collection state\n");
    }
}
                

// Process each item in the collection
DWORD dwCount = GetDateCollectionLength(hCollection);

if (dwCount == DATE_LOG_SENTINEL) {
    printf("Invalid collection\n");
    return;
}

if (dwCount == 0) {
    printf("Collection is empty, nothing to process\n");
    return;
}

for (DWORD i = 0; i < dwCount; i++) {
    DATE_ITEM_HANDLE hItem = GetDateLogFirstDate(hCollection);
    if (hItem == NULL) {
        printf("Failed to get date item %u\n", i);
        break;
    }
    
    DATE_STRUCT date = {0};
    GetDateItemDate(hItem, &date);
    
    printf("Date %u: %04d-%02d-%02d\n", i, 
           date.year, date.month, date.day);
}
                

// Allocate buffer sized to collection
DWORD dwLength = GetDateCollectionLength(hCollection);

if (dwLength == DATE_LOG_SENTINEL || dwLength == 0) {
    printf("Cannot allocate buffer for empty/invalid collection\n");
    return NULL;
}

// Each date item is sizeof(DATE_STRUCT) bytes
SIZE_T cbBuffer = dwLength * sizeof(DATE_STRUCT);

PDATE_STRUCT pDates = (PDATE_STRUCT)malloc(cbBuffer);
if (pDates == NULL) {
    printf("Failed to allocate %zu bytes\n", cbBuffer);
    return NULL;
}

printf("Allocated %zu bytes for %u dates\n", cbBuffer, dwLength);
return pDates;
                

Thread Safety and Synchronization

Mutex Acquisition

Concurrent Access Scenarios

Visibility Guarantees

• Mutex acquisition provides acquire semantics on read
• Memory barriers ensure visibility of changes made by other threads
• Value read is consistent snapshot at point of mutex acquisition
• Value may become stale immediately after mutex release if another thread modifies collection

Important Notes and Considerations

Return Value Semantics

Related Functions

• GetDateCollectionMaximumLength() – Get the maximum capacity
• GetDateLogFirstDate() – Get the first date item
• GetDateLogLastDate() – Get the last date item
• InitializeDateLogHandle() – Create a new collection
• CloseDateLogHandle() – Close and free a collection
• IsValidDateLogHandle() – Validate a handle

Performance Considerations

• O(1) time complexity; no iteration required
• Minimal overhead: single validation + mutex acquire + field read
• Safe for high-frequency calling; no resource leaks
• 5-second timeout adds latency only under contention

Common Pitfalls

• Not Checking Return Value: Always check for DATE_LOG_SENTINEL before using the length
• Treating 0 as Error: Empty collections return 0, which is valid; only DATE_LOG_SENTINEL indicates error
• Ignoring Timeout: Under high contention, the function may timeout and return sentinel; don't retry immediately
• Using Stale Values: Length may change after the call; don't rely on it for loop bounds without re-checking

Updates and Changes

• SAL Annotations Updated: Now uses _On_failure_(return > DATE_LOG_MAX) instead of _Success_
• Redundant Validation Removed: Wrapper no longer checks pContext NULL; delegated to caller validation
• Thread Safety Improved: Defensive mutex validation added in callee