GetDateCollectionMaximumLength

Overview

GetDateCollectionMaximumLength returns the maximum capacity (allocation limit) of a date collection handle. This function provides thread-safe access to the collection's maximum length by acquiring the internal mutex and reading the maximum length field.

Purpose

Get the maximum number of date items that can be stored in a collection. This is useful for:

• Calculating collection utilization percentage
• Determining remaining capacity before collection is full
• Pre-allocating resources based on collection limits
• Validating that collections won't exceed system limits
• Planning merge operations with capacity constraints

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
• Immutable value throughout collection lifetime (set at initialization)
• No side effects on the collection state

Function Signature

DWORD _Check_return_ _On_failure_(return > DATE_LOG_MAX) GetDateCollectionMaximumLength(
    _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 resource misallocation
_On_failure_(return > DATE_LOG_MAX) : On failure, return value will exceed DATE_LOG_MAX (range 0x000000 to 0x001388)
                

Parameters

Return Values

Success Case

Returns the maximum capacity of the collection. Range is 1 through DATE_LOG_MAX (5000 items maximum). The returned value is always >= 1 because collections cannot be created with zero capacity.

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

Constant Reference

Checking Return Values

// Pattern 1: Simple validity check
DWORD dwMaxLength = GetDateCollectionMaximumLength(hCollection);
if (dwMaxLength == DATE_LOG_SENTINEL) {
    // Error occurred
    printf("Failed to get collection maximum length\n");
    // Close handle and retry
} else if (dwMaxLength == 0 || dwMaxLength > DATE_LOG_MAX) {
    // Data corruption detected
    printf("ERROR: Invalid maximum length: %u\n", dwMaxLength);
} else {
    // Valid maximum capacity
    printf("Collection capacity: %u items\n", dwMaxLength);
}

// Pattern 2: Calculate utilization
DWORD dwCurrentLen = GetDateCollectionLength(hCollection);
DWORD dwMaxLen = GetDateCollectionMaximumLength(hCollection);

if (dwCurrentLen != DATE_LOG_SENTINEL && dwMaxLen != DATE_LOG_SENTINEL) {
    double utilization = (100.0 * dwCurrentLen) / dwMaxLen;
    printf("Utilization: %.1f%% (%u of %u items)\n", 
        utilization, dwCurrentLen, dwMaxLen);
    
    if (utilization > 90.0) {
        printf("WARNING: Collection nearly full!\n");
    }
}

// Pattern 3: Check available capacity
DWORD dwRemaining = dwMaxLen - dwCurrentLen;
printf("Remaining capacity: %u items\n", dwRemaining);
            

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 GetDateLogCoreMaxLength() which:
   • Re-validates the core pointer
   • Acquires the core's mutex with 5-second timeout
   • Reads the dwMaxLength field inside the mutex
   • Releases the mutex
5. Return Result:
   Returns the maximum length value or DATE_LOG_SENTINEL if any step fails

Value Immutability

The maximum length of a collection is established at initialization and never changes:

• Set via InitializeDateLogHandle(dwMaximumLength, ...)
• Stored in DATE_LOG_CORE.dwMaxLength
• Cannot be modified through any API function
• Represents a hard limit on collection size
• Multiple calls always return the same value (barring errors)

Thread Safety

The function is fully thread-safe:

• Mutex Protection: The core's max 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
• Value Stability: No risk of reading torn values (4-byte integer on aligned boundary)

Comparison with GetDateCollectionLength

Usage Examples

#include "datelog.h"

DWORD dwCurrentLength = GetDateCollectionLength(hMyCollection);
DWORD dwMaxLength = GetDateCollectionMaximumLength(hMyCollection);

if (dwCurrentLength == DATE_LOG_SENTINEL || dwMaxLength == DATE_LOG_SENTINEL) {
    printf("ERROR: Failed to get collection information\n");
    goto error_cleanup;
}

DWORD dwRemaining = dwMaxLength - dwCurrentLength;

if (dwRemaining < 100) {
    printf("WARNING: Only %u items of capacity remaining\n", dwRemaining);
    printf("Collection is %.1f%% full\n", 
        (100.0 * dwCurrentLength) / dwMaxLength);
} else {
    printf("Plenty of space available (%u items)\n", dwRemaining);
}

// ... continue with operation ...

error_cleanup:
    CloseDateLogHandle(hMyCollection);
    return FALSE;
                

// Allocate buffer sized to collection's maximum capacity
DWORD dwMaxLength = GetDateCollectionMaximumLength(hCollection);

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

if (dwMaxLength > DATE_LOG_MAX) {
    printf("ERROR: Collection capacity exceeds maximum allowed\n");
    return NULL;
}

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

// Check for integer overflow
if (cbBuffer / sizeof(DATE_STRUCT) != dwMaxLength) {
    printf("ERROR: Buffer size calculation overflow\n");
    return NULL;
}

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 maximum %u dates\n", cbBuffer, dwMaxLength);
return pDates;
                

void PrintCollectionStatistics(DATE_COLLECTION_HANDLE hCollection) {
    DWORD dwLength = GetDateCollectionLength(hCollection);
    DWORD dwMaxLength = GetDateCollectionMaximumLength(hCollection);
    
    if (dwLength == DATE_LOG_SENTINEL || dwMaxLength == DATE_LOG_SENTINEL) {
        printf("Collection is invalid or inaccessible\n");
        return;
    }
    
    // Validate data integrity
    if (dwLength > dwMaxLength) {
        printf("ERROR: Current length (%u) exceeds maximum (%u)\n", 
            dwLength, dwMaxLength);
        return;
    }
    
    // Calculate statistics
    DWORD dwRemaining = dwMaxLength - dwLength;
    double percentUsed = (100.0 * dwLength) / dwMaxLength;
    double percentFree = 100.0 - percentUsed;
    
    printf("=== Collection Statistics ===\n");
    printf("Current items:    %u\n", dwLength);
    printf("Maximum capacity: %u\n", dwMaxLength);
    printf("Remaining space:  %u items\n", dwRemaining);
    printf("Utilization:      %.1f%% used, %.1f%% free\n", 
        percentUsed, percentFree);
    
    // Alert on capacity thresholds
    if (percentUsed >= 90.0) {
        printf("⚠ CRITICAL: Collection is nearly full!\n");
    } else if (percentUsed >= 75.0) {
        printf("⚠ WARNING: Collection is getting full\n");
    } else if (percentUsed >= 50.0) {
        printf("ℹ INFO: Collection is half-full\n");
    }
}
                

// Before merging, check if result will fit
DWORD dwDestCurrent = GetDateCollectionLength(hDestLog);
DWORD dwDestMax = GetDateCollectionMaximumLength(hDestLog);
DWORD dwSourceLength = GetDateCollectionLength(hSourceLog);

if (dwDestCurrent == DATE_LOG_SENTINEL || 
    dwDestMax == DATE_LOG_SENTINEL || 
    dwSourceLength == DATE_LOG_SENTINEL) {
    printf("ERROR: Cannot get collection sizes\n");
    return FALSE;
}

// Estimate space needed (conservative: assume all source items are new)
DWORD dwEstimatedTotal = dwDestCurrent + dwSourceLength;

if (dwEstimatedTotal > dwDestMax) {
    printf("ERROR: Merge would exceed capacity\n");
    printf("Destination: %u current + %u source = %u total\n", 
        dwDestCurrent, dwSourceLength, dwEstimatedTotal);
    printf("Maximum capacity: %u\n", dwDestMax);
    printf("Shortfall: %u items\n", dwEstimatedTotal - dwDestMax);
    return FALSE;
} else {
    DWORD dwRemaining = dwDestMax - dwEstimatedTotal;
    printf("Merge will fit with %u items to spare\n", dwRemaining);
    
    // Proceed with merge
    return SUCCEEDED(MergeDateLogHandle(hDestLog, hSourceLog, 
                                        DATE_RANGE_MERGE_FAVOR_SOURCE));
}
                

Thread Safety and Synchronization

Mutex Acquisition

Concurrent Access Scenarios

Visibility Guarantees

• Mutex acquisition provides acquire semantics on read
• Memory barriers ensure visibility across all threads
• Value is stable and never changes after initialization
• Safe to cache returned value (it will never change)

Optimization Opportunity

Important Notes and Considerations

Return Value Semantics

Immutability of Maximum Capacity

• The maximum capacity is set at collection initialization
• It cannot be changed through any API function
• It is fixed for the lifetime of the collection
• Safe to cache the value for performance optimization

Related Functions

• GetDateCollectionLength() – Get current number of items
• InitializeDateLogHandle() – Create collection with specified max capacity
• CloseDateLogHandle() – Close and free a collection
• IsValidDateLogHandle() – Validate a handle
• GetDateLogFirstDate() – Get first date item
• GetDateLogLastDate() – Get last date item

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 extreme contention
• Consider caching result since value never changes

Common Pitfalls

• Not Checking Return Value: Always check for DATE_LOG_SENTINEL before using the result
• Treating 0 as Valid: A return value of 0 indicates data corruption; only 1 to DATE_LOG_MAX are valid
• Assuming It Equals Current Length: Maximum and current length are different; don't confuse them
• Ignoring Timeout: Under high contention, the function may timeout; don't retry immediately
• Not Caching: Since value never changes, caching avoids redundant mutex calls

Relationship to DATE_LOG_MAX Constant

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