File writer with automatic log rotation support. More...

#include <rotating_file_writer.h>

Inheritance diagram for kcenon::logger::rotating_file_writer:

Collaboration diagram for kcenon::logger::rotating_file_writer:

Public Member Functions
	rotating_file_writer (const std::string &filename, size_t max_size, size_t max_files, size_t check_interval=100)
	Construct with size-based rotation.

	rotating_file_writer (const std::string &filename, rotation_type type, size_t max_files, size_t check_interval=100)
	Construct with time-based rotation.

	rotating_file_writer (const std::string &filename, rotation_type type, size_t max_size, size_t max_files, size_t check_interval=100)
	Construct with combined size and time rotation.

std::string	get_name () const override
	Get writer name.

void	rotate ()
	Manually trigger log rotation (thread-safe)

common::VoidResult	write (const log_entry &entry) override
	Write operation with automatic rotation check.

Public Member Functions inherited from kcenon::logger::file_writer
	file_writer (const std::string &filename, bool append=true, std::unique_ptr< log_formatter_interface > formatter=nullptr)
	Constructor.

	~file_writer () override
	Destructor.

	file_writer (const file_writer &)=delete

file_writer &	operator= (const file_writer &)=delete

	file_writer (file_writer &&)=delete

file_writer &	operator= (file_writer &&)=delete

common::VoidResult	flush () override
	Flush file stream.

common::VoidResult	close () override
	Close the file.

bool	is_open () const override
	Check if file is open.

bool	is_healthy () const override
	Check if writer is healthy.

size_t	get_file_size () const
	Get current file size.

Public Member Functions inherited from kcenon::logger::log_writer_interface
virtual	~log_writer_interface ()=default

Private Member Functions
bool	should_rotate () const
	Check if rotation should occur.

void	perform_rotation ()
	Perform the actual rotation operation.

std::string	generate_rotated_filename (int index=-1) const
	Generate filename for rotated log.

void	cleanup_old_files ()
	Remove old backup files beyond max_files limit.

std::vector< std::string >	get_backup_files () const
	Get list of existing backup files.

bool	should_rotate_by_time () const
	Check if time-based rotation should occur.

std::size_t	get_file_size () const
	Get current file size from filesystem.

Private Attributes
rotation_type	rotation_type_

size_t	max_size_

size_t	max_files_

size_t	check_interval_
	Number of writes between rotation checks.

size_t	writes_since_check_ {0}
	Counter for writes since last check.

std::string	base_filename_

std::string	file_extension_

std::chrono::system_clock::time_point	last_rotation_time_

std::chrono::system_clock::time_point	current_period_start_

Additional Inherited Members
Static Public Attributes inherited from kcenon::logger::sync_writer_tag
static constexpr writer_category	category = writer_category::synchronous

Protected Member Functions inherited from kcenon::logger::file_writer
std::string	format_entry (const log_entry &entry) const
	Format a log entry using the current formatter.

common::VoidResult	open_internal ()
	Open the file (internal, caller must hold mutex)

void	close_internal ()
	Close the file (internal, caller must hold mutex)

std::mutex &	get_mutex () const
	Access the writer mutex for extended operations.

Protected Attributes inherited from kcenon::logger::file_writer
std::string	filename_

bool	append_mode_

std::ofstream	file_stream_

std::atomic< bool >	is_open_ {false}

std::atomic< size_t >	bytes_written_ {0}

std::unique_ptr< log_formatter_interface >	formatter_

std::mutex	mutex_

Detailed Description

File writer with automatic log rotation support.

This writer extends file_writer to add automatic log rotation based on file size, time intervals, or both. When rotation occurs, the current log file is renamed with a timestamp or index, and a new file is created.

Rotation strategies:

Size-based: Rotates when file reaches max_size bytes
Time-based: Rotates daily or hourly
Combined: Rotates when either condition is met

Thread Safety:

All public methods are thread-safe
Uses mutex from thread_safe_writer base class

Category: Synchronous (blocking I/O, inherits from file_writer)

Since: 1.0.0; 1.3.0 Refactored to use thread_safe_writer via file_writer; 1.4.0 Inherits sync_writer_tag from file_writer

Definition at line 60 of file rotating_file_writer.h.

Constructor & Destructor Documentation

◆ rotating_file_writer() [1/3]

kcenon::logger::rotating_file_writer::rotating_file_writer	(	const std::string &	filename,
		size_t	max_size,
		size_t	max_files,
		size_t	check_interval = 100 )

Construct with size-based rotation.

Parameters

filename	Path to the log file
max_size	Maximum file size in bytes before rotation
max_files	Maximum number of backup files to keep
check_interval	Number of writes between rotation checks (default: 100)

Definition at line 15 of file rotating_file_writer.cpp.

    : file_writer(filename, true)
    , rotation_type_(rotation_type::size)
    , max_size_(max_size)
    , max_files_(max_files)
    , check_interval_(check_interval)
    , last_rotation_time_(std::chrono::system_clock::now())
    , current_period_start_(std::chrono::system_clock::now()) {
 
    // Extract base filename and extension
    std::filesystem::path path(filename);
    base_filename_ = path.stem().string();
    file_extension_ = path.extension().string();
    if (file_extension_.empty()) {
        file_extension_ = ".log";
    }
}

References base_filename_, and file_extension_.

◆ rotating_file_writer() [2/3]

kcenon::logger::rotating_file_writer::rotating_file_writer	(	const std::string &	filename,
		rotation_type	type,
		size_t	max_files,
		size_t	check_interval = 100 )

Construct with time-based rotation.

Parameters

filename	Path to the log file
type	Rotation type (daily or hourly)
max_files	Maximum number of backup files to keep
check_interval	Number of writes between rotation checks (default: 100)

Definition at line 36 of file rotating_file_writer.cpp.

    : file_writer(filename, true)
    , rotation_type_(type)
    , max_size_(0)
    , max_files_(max_files)
    , check_interval_(check_interval)
    , last_rotation_time_(std::chrono::system_clock::now())
    , current_period_start_(std::chrono::system_clock::now()) {
 
    // Extract base filename and extension
    std::filesystem::path path(filename);
    base_filename_ = path.stem().string();
    file_extension_ = path.extension().string();
    if (file_extension_.empty()) {
        file_extension_ = ".log";
    }
}

References base_filename_, and file_extension_.

◆ rotating_file_writer() [3/3]

kcenon::logger::rotating_file_writer::rotating_file_writer	(	const std::string &	filename,
		rotation_type	type,
		size_t	max_size,
		size_t	max_files,
		size_t	check_interval = 100 )

Construct with combined size and time rotation.

Parameters

filename	Path to the log file
type	Must be rotation_type::size_and_time
max_size	Maximum file size in bytes before rotation
max_files	Maximum number of backup files to keep
check_interval	Number of writes between rotation checks (default: 100)

Exceptions

std::invalid_argument if type is not size_and_time

Definition at line 57 of file rotating_file_writer.cpp.

    : file_writer(filename, true)
    , rotation_type_(type)
    , max_size_(max_size)
    , max_files_(max_files)
    , check_interval_(check_interval)
    , last_rotation_time_(std::chrono::system_clock::now())
    , current_period_start_(std::chrono::system_clock::now()) {
 
    if (type != rotation_type::size_and_time) {
        throw std::invalid_argument("This constructor is only for size_and_time rotation");
    }
 
    // Extract base filename and extension
    std::filesystem::path path(filename);
    base_filename_ = path.stem().string();
    file_extension_ = path.extension().string();
    if (file_extension_.empty()) {
        file_extension_ = ".log";
    }
}

References base_filename_, file_extension_, and kcenon::logger::size_and_time.

Member Function Documentation

◆ cleanup_old_files()

void kcenon::logger::rotating_file_writer::cleanup_old_files ( )

private

Remove old backup files beyond max_files limit.

Definition at line 250 of file rotating_file_writer.cpp.

                                             {
    auto backup_files = get_backup_files();
 
    if (backup_files.size() > max_files_) {
        // Sort by modification time (oldest first)
        std::sort(backup_files.begin(), backup_files.end(),
                 [](const std::string& a, const std::string& b) {
                     return std::filesystem::last_write_time(a) <
                            std::filesystem::last_write_time(b);
                 });
 
        // Remove oldest files
        size_t files_to_remove = backup_files.size() - max_files_;
        for (size_t i = 0; i < files_to_remove; ++i) {
            auto remove_result = utils::try_write_operation([&]() -> common::VoidResult {
                std::filesystem::remove(backup_files[i]);
                return common::ok();
            }, logger_error_code::file_rotation_failed);
 
            if (remove_result.is_err()) {
                std::cerr << "Failed to remove old log file: " << remove_result.error().message << std::endl;
            }
        }
    }
}

References kcenon::logger::file_rotation_failed, get_backup_files(), max_files_, kcenon::common::ok(), and kcenon::logger::utils::try_write_operation().

Referenced by perform_rotation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ generate_rotated_filename()

std::string kcenon::logger::rotating_file_writer::generate_rotated_filename ( int index = -1 ) const

private

Generate filename for rotated log.

Parameters

index Optional index for size-based rotation (-1 for auto)

Definition at line 195 of file rotating_file_writer.cpp.

                                                                         {
    std::ostringstream oss;
    std::filesystem::path dir = std::filesystem::path(filename_).parent_path();
 
    if (!dir.empty()) {
        oss << dir.string() << "/";
    }
 
    // Build: base + extension + separator + timestamp/index
    // Example: "test.log.1" instead of "test.1.log"
    oss << base_filename_ << file_extension_;
 
    // Add timestamp or index
    auto now = std::chrono::system_clock::now();
    auto time_t = std::chrono::system_clock::to_time_t(now);
 
    // Use thread-safe time conversion
    std::tm tm_buf{};
#ifdef _WIN32
    localtime_s(&tm_buf, &time_t);  // Windows thread-safe version
#else
    localtime_r(&time_t, &tm_buf);  // POSIX thread-safe version
#endif
 
    switch (rotation_type_) {
        case rotation_type::size:
            if (index >= 0) {
                oss << "." << index;
            } else {
                // Find next available index
                std::string base_with_ext = oss.str();
                int next_index = 1;
                while (std::filesystem::exists(base_with_ext + "." + std::to_string(next_index))) {
                    next_index++;
                }
                oss << "." << next_index;
            }
            break;
 
        case rotation_type::daily:
            oss << "." << std::put_time(&tm_buf, "%Y%m%d");
            break;
 
        case rotation_type::hourly:
            oss << "." << std::put_time(&tm_buf, "%Y%m%d_%H");
            break;
 
        case rotation_type::size_and_time:
            oss << "." << std::put_time(&tm_buf, "%Y%m%d_%H%M%S");
            break;
    }
 
    return oss.str();
}

References base_filename_, kcenon::logger::daily, file_extension_, kcenon::logger::file_writer::filename_, kcenon::logger::hourly, rotation_type_, kcenon::logger::size, and kcenon::logger::size_and_time.

Referenced by perform_rotation().

Here is the caller graph for this function:

◆ get_backup_files()

std::vector< std::string > kcenon::logger::rotating_file_writer::get_backup_files ( ) const

private

Get list of existing backup files.

Definition at line 276 of file rotating_file_writer.cpp.

                                                                  {
    std::vector<std::string> files;
    std::filesystem::path dir = std::filesystem::path(filename_).parent_path();
    if (dir.empty()) {
        dir = ".";
    }
 
    // Create regex pattern for backup files
    // Pattern: base_filename + file_extension + "." + (number or timestamp)
    // Example: "test_rotating.log.1" or "test.log.20250108"
    std::string escaped_ext = std::regex_replace(file_extension_, std::regex(R"(\.)"), R"(\\.)");
    std::string pattern = base_filename_ + escaped_ext + R"(\.(\d+|\d{8}|\d{8}_\d{2}|\d{8}_\d{6}))";
    std::regex backup_regex(pattern);
 
    // Use error handling utility for directory iteration
    auto result = utils::try_write_operation([&]() -> common::VoidResult {
        for (const auto& entry : std::filesystem::directory_iterator(dir)) {
            if (entry.is_regular_file()) {
                std::string filename = entry.path().filename().string();
                if (std::regex_match(filename, backup_regex)) {
                    files.push_back(entry.path().string());
                }
            }
        }
        return common::ok();
    }, logger_error_code::file_rotation_failed);
 
    if (result.is_err()) {
        std::cerr << "Error listing backup files: " << result.error().message << std::endl;
    }
 
    return files;
}

References base_filename_, file_extension_, kcenon::logger::file_rotation_failed, kcenon::logger::file_writer::filename_, kcenon::common::ok(), and kcenon::logger::utils::try_write_operation().

Referenced by cleanup_old_files().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_file_size()

std::size_t kcenon::logger::rotating_file_writer::get_file_size ( ) const

private

Get current file size from filesystem.

Definition at line 347 of file rotating_file_writer.cpp.

                                                    {
    // IMPORTANT: This method should only be called while holding the mutex
    // to avoid race conditions with concurrent writes and file rotation.
    //
    // Race condition example:
    // - Thread A: Calls should_rotate() -> get_file_size() reads filesystem
    // - Thread B: Simultaneously writing, bytes_written_ is updating
    // - Result: get_file_size() returns stale data, rotation check is incorrect
    //
    // Better approach: Always use bytes_written_.load() which is atomic and
    // thread-safe. Only call filesystem functions during actual rotation when
    // the caller already holds the mutex.
 
    if (!file_stream_.is_open()) {
        return 0;
    }
 
    // Prefer atomic counter for thread safety
    // Only fall back to filesystem if absolutely necessary
    std::size_t atomic_size = bytes_written_.load(std::memory_order_relaxed);
 
    // Optional: Validate with filesystem size for debugging
    // (Remove in production for performance)
    #ifdef DEBUG_FILE_SIZE_VALIDATION
    std::error_code ec;
    auto fs_size = std::filesystem::file_size(filename_, ec);
    if (!ec && fs_size != atomic_size) {
        // Log discrepancy for debugging
        std::cerr << "File size mismatch: atomic=" << atomic_size
                  << " filesystem=" << fs_size << std::endl;
    }
    #endif
 
    return atomic_size;
}

References kcenon::logger::file_writer::bytes_written_, kcenon::logger::file_writer::file_stream_, and kcenon::logger::file_writer::filename_.

Referenced by should_rotate().

Here is the caller graph for this function:

◆ get_name()

std::string kcenon::logger::rotating_file_writer::get_name ( ) const

inlineoverridevirtual

Get writer name.

Reimplemented from kcenon::logger::file_writer.

Definition at line 104 of file rotating_file_writer.h.

104{ return "rotating_file"; }

◆ perform_rotation()

void kcenon::logger::rotating_file_writer::perform_rotation ( )

private

Perform the actual rotation operation.

Note: Caller must hold the mutex

Definition at line 137 of file rotating_file_writer.cpp.

                                            {
    // IMPORTANT: Caller must hold the mutex before calling this method
    // This ensures thread safety for all file operations and mutable state modifications
 
    // Close current file
    if (file_stream_.is_open()) {
        file_stream_.flush();
        file_stream_.close();
    }
 
    // Generate new filename for the current log
    std::string rotated_name = generate_rotated_filename();
 
    // Rename current file (with error handling)
    auto rename_result = utils::try_write_operation([&]() -> common::VoidResult {
        if (std::filesystem::exists(filename_)) {
            std::filesystem::rename(filename_, rotated_name);
        }
        return common::ok();
    }, logger_error_code::file_rotation_failed);
 
    if (rename_result.is_err()) {
        std::cerr << "Failed to rotate log file: " << rename_result.error().message << std::endl;
    }
 
    // Clean up old files
    cleanup_old_files();
 
    // Open new file (with error handling)
    auto open_result = utils::try_open_operation([&]() -> common::VoidResult {
        std::filesystem::path file_path(filename_);
        std::filesystem::path dir = file_path.parent_path();
 
        auto dir_result = utils::ensure_directory_exists(dir);
        if (dir_result.is_err()) return dir_result;
 
        auto mode = append_mode_ ? std::ios::app : std::ios::trunc;
        file_stream_.open(filename_, std::ios::out | mode);
 
        if (file_stream_.is_open()) {
            bytes_written_ = 0;
        }
 
        return common::ok();
    });
 
    if (open_result.is_err()) {
        std::cerr << "Failed to open new log file: " << open_result.error().message << std::endl;
    }
 
    // Update rotation time - protected by mutex
    last_rotation_time_ = std::chrono::system_clock::now();
    current_period_start_ = last_rotation_time_;
 
    // Reset write counter after rotation
    writes_since_check_ = 0;
}

References kcenon::logger::file_writer::append_mode_, kcenon::logger::file_writer::bytes_written_, cleanup_old_files(), current_period_start_, kcenon::logger::utils::ensure_directory_exists(), kcenon::logger::file_rotation_failed, kcenon::logger::file_writer::file_stream_, kcenon::logger::file_writer::filename_, generate_rotated_filename(), last_rotation_time_, kcenon::common::ok(), kcenon::logger::utils::try_open_operation(), kcenon::logger::utils::try_write_operation(), and writes_since_check_.

Referenced by rotate(), and write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rotate()

void kcenon::logger::rotating_file_writer::rotate ( )

Manually trigger log rotation (thread-safe)

Definition at line 114 of file rotating_file_writer.cpp.

                                  {
    // Public API for manual rotation
    std::lock_guard<std::mutex> lock(get_mutex());
    perform_rotation();
}

References kcenon::logger::file_writer::get_mutex(), and perform_rotation().

Here is the call graph for this function:

◆ should_rotate()

bool kcenon::logger::rotating_file_writer::should_rotate ( ) const

private

Check if rotation should occur.

Definition at line 120 of file rotating_file_writer.cpp.

                                               {
    switch (rotation_type_) {
        case rotation_type::size:
            return get_file_size() >= max_size_;
            
        case rotation_type::daily:
        case rotation_type::hourly:
            return should_rotate_by_time();
            
        case rotation_type::size_and_time:
            return get_file_size() >= max_size_ || should_rotate_by_time();
            
        default:
            return false;
    }
}

References kcenon::logger::daily, get_file_size(), kcenon::logger::hourly, max_size_, rotation_type_, should_rotate_by_time(), kcenon::logger::size, and kcenon::logger::size_and_time.

Referenced by write().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ should_rotate_by_time()

bool kcenon::logger::rotating_file_writer::should_rotate_by_time ( ) const

private

Check if time-based rotation should occur.

Definition at line 310 of file rotating_file_writer.cpp.

                                                       {
    auto now = std::chrono::system_clock::now();
    
    switch (rotation_type_) {
        case rotation_type::daily:
        case rotation_type::size_and_time: {
            // Check if we're in a new day
            auto now_time_t = std::chrono::system_clock::to_time_t(now);
            auto start_time_t = std::chrono::system_clock::to_time_t(current_period_start_);
 
            // Use thread-safe time conversion
            std::tm now_tm{};
            std::tm start_tm{};
#ifdef _WIN32
            localtime_s(&now_tm, &now_time_t);
            localtime_s(&start_tm, &start_time_t);
#else
            localtime_r(&now_time_t, &now_tm);
            localtime_r(&start_time_t, &start_tm);
#endif
 
            return now_tm.tm_year != start_tm.tm_year ||
                   now_tm.tm_mon != start_tm.tm_mon ||
                   now_tm.tm_mday != start_tm.tm_mday;
        }
        
        case rotation_type::hourly: {
            // Check if we're in a new hour
            auto duration = now - current_period_start_;
            return duration >= std::chrono::hours(1);
        }
        
        default:
            return false;
    }
}

References current_period_start_, kcenon::logger::daily, kcenon::logger::hourly, rotation_type_, and kcenon::logger::size_and_time.

Referenced by should_rotate().

Here is the caller graph for this function:

◆ write()

common::VoidResult kcenon::logger::rotating_file_writer::write ( const log_entry & entry )

overridevirtual

Write operation with automatic rotation check.

Parameters

entry The log entry to write (includes structured fields)

Since: 3.4.0; 3.5.0 This is now the only write implementation (legacy API removed); 4.0.0 Changed to override write() directly after Decorator pattern refactoring

Reimplemented from kcenon::logger::file_writer.

Definition at line 83 of file rotating_file_writer.cpp.

                                                                   {
    std::lock_guard<std::mutex> lock(get_mutex());
 
    // Check precondition
    if (!file_stream_.is_open()) {
        return make_logger_void_result(logger_error_code::file_write_failed, "File stream is not open");
    }
 
    // Format and write - preserves all structured fields
    std::string formatted = format_entry(entry);
    file_stream_ << formatted << '\n';
    bytes_written_.fetch_add(formatted.size() + 1);
 
    // Verify stream state
    if (file_stream_.fail()) {
        return make_logger_void_result(logger_error_code::file_write_failed, "Write failed");
    }
 
    // Periodic rotation check optimization (Phase 2)
    ++writes_since_check_;
 
    if (writes_since_check_ >= check_interval_) {
        if (should_rotate()) {
            perform_rotation();
        }
        writes_since_check_ = 0;
    }
 
    return common::ok();
}

References kcenon::logger::file_writer::bytes_written_, check_interval_, kcenon::logger::file_writer::file_stream_, kcenon::logger::file_write_failed, kcenon::logger::file_writer::format_entry(), kcenon::logger::file_writer::get_mutex(), kcenon::logger::make_logger_void_result(), kcenon::common::ok(), perform_rotation(), should_rotate(), and writes_since_check_.

Here is the call graph for this function:

Member Data Documentation

◆ base_filename_

std::string kcenon::logger::rotating_file_writer::base_filename_

private

Definition at line 165 of file rotating_file_writer.h.

Referenced by generate_rotated_filename(), get_backup_files(), rotating_file_writer(), rotating_file_writer(), and rotating_file_writer().

◆ check_interval_

size_t kcenon::logger::rotating_file_writer::check_interval_

private

Number of writes between rotation checks.

Definition at line 163 of file rotating_file_writer.h.

Referenced by write().

◆ current_period_start_

std::chrono::system_clock::time_point kcenon::logger::rotating_file_writer::current_period_start_

private

Definition at line 168 of file rotating_file_writer.h.

Referenced by perform_rotation(), and should_rotate_by_time().

◆ file_extension_

std::string kcenon::logger::rotating_file_writer::file_extension_

private

Definition at line 166 of file rotating_file_writer.h.

Referenced by generate_rotated_filename(), get_backup_files(), rotating_file_writer(), rotating_file_writer(), and rotating_file_writer().

◆ last_rotation_time_

std::chrono::system_clock::time_point kcenon::logger::rotating_file_writer::last_rotation_time_

private

Definition at line 167 of file rotating_file_writer.h.

Referenced by perform_rotation().

◆ max_files_

size_t kcenon::logger::rotating_file_writer::max_files_

private

Definition at line 162 of file rotating_file_writer.h.

Referenced by cleanup_old_files().

◆ max_size_

size_t kcenon::logger::rotating_file_writer::max_size_

private

Definition at line 161 of file rotating_file_writer.h.

Referenced by should_rotate().

◆ rotation_type_

rotation_type kcenon::logger::rotating_file_writer::rotation_type_

private

Definition at line 160 of file rotating_file_writer.h.

Referenced by generate_rotated_filename(), should_rotate(), and should_rotate_by_time().

◆ writes_since_check_

size_t kcenon::logger::rotating_file_writer::writes_since_check_ {0}

private

Counter for writes since last check.

Definition at line 164 of file rotating_file_writer.h.

164{0};

Referenced by perform_rotation(), and write().

The documentation for this class was generated from the following files:

include/kcenon/logger/writers/rotating_file_writer.h
src/impl/writers/rotating_file_writer.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ rotating_file_writer() [1/3]

◆ rotating_file_writer() [2/3]

◆ rotating_file_writer() [3/3]

Member Function Documentation

◆ cleanup_old_files()

◆ generate_rotated_filename()

◆ get_backup_files()

◆ get_file_size()

◆ get_name()

◆ perform_rotation()

◆ rotate()

◆ should_rotate()

◆ should_rotate_by_time()

◆ write()

Member Data Documentation

◆ base_filename_

◆ check_interval_

◆ current_period_start_

◆ file_extension_

◆ last_rotation_time_

◆ max_files_

◆ max_size_

◆ rotation_type_

◆ writes_since_check_