Class FileHandleManager

Nested Relationships

Nested Types

Class Documentation

class FileHandleManager

Thread-safe file handle resource management system.

The FileHandleManager prevents file handle exhaustion by limiting the number of files that can be open simultaneously across all threads. It uses either C++20 counting_semaphore (preferred) or a fallback implementation with mutex and condition variables for older compilers.

Design

The manager uses RAII (Resource Acquisition Is Initialization) through the FileGuard class to ensure file handles are properly released even if exceptions occur during file processing.

Usage Pattern

  1. Call acquire() to get a FileGuard

  2. Check is_acquired() to ensure handle was obtained

  3. Open file if guard is acquired

  4. Process file content

  5. FileGuard destructor automatically releases handle

Note

The manager is designed to prevent system file handle exhaustion which can cause application crashes or system instability

Public Functions

FileGuard acquire()

Acquire a file handle guard.

Attempts to acquire a file handle and returns a FileGuard for RAII management. The guard may not have successfully acquired a handle if all handles are currently in use.

Returns:

FileGuard object (check is_acquired() for success)

void release()

Release a file handle back to the pool.

Manually releases a file handle. Typically not needed as FileGuard handles automatic release, but available for advanced usage patterns.

Note

This should only be called if a handle was successfully acquired

class FileGuard

RAII guard for automatic file handle management.

The FileGuard class provides automatic file handle acquisition and release using RAII principles. It ensures that file handles are properly released even if exceptions occur during file processing.

Features

  • Automatic handle release in destructor

  • Move semantics for efficient transfer

  • Non-copyable to prevent handle duplication

  • Status checking to verify successful acquisition

Note

FileGuard objects should be short-lived and created immediately before file operations to minimize handle holding time

Public Functions

explicit FileGuard(FileHandleManager *mgr)

Constructor - attempts to acquire file handle.

Attempts to acquire a file handle from the manager. Check is_acquired() to determine if the acquisition was successful.

Parameters:

mgr – Pointer to the FileHandleManager

~FileGuard()

Destructor - automatically releases file handle.

Releases the file handle back to the manager if it was successfully acquired. This ensures proper cleanup even in exception scenarios.

FileGuard(const FileGuard&) = delete

Copy constructor (deleted)

FileGuard is non-copyable to prevent accidental handle duplication which could lead to resource leaks or double-release errors.

FileGuard &operator=(const FileGuard&) = delete

Copy assignment operator (deleted)

FileGuard is non-copyable to prevent accidental handle duplication which could lead to resource leaks or double-release errors.

FileGuard(FileGuard &&other) noexcept

Move constructor for efficient transfer.

Transfers ownership of the file handle from another FileGuard. The source guard becomes invalid after the move.

Parameters:

other – FileGuard to move from

FileGuard &operator=(FileGuard &&other) noexcept

Move assignment operator for efficient transfer.

Transfers ownership of the file handle from another FileGuard. Releases any currently held handle before acquiring the new one.

Parameters:

other – FileGuard to move from

Returns:

Reference to this FileGuard

inline bool is_acquired() const

Check if file handle was successfully acquired.

Always check this before attempting file operations to ensure a handle is available. If false, defer the operation or retry later.

Returns:

true if handle is available for use, false otherwise