mappedfile.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of \dxl - A doxygen post-processor that allows to define smarter
/// <b>Doxygen</b>-links.
///
/// \emoji :copyright: 2025-2026 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef HPP_DXL_SEQUENTIAL_FILE_VIEW_TODORENAME
#define HPP_DXL_SEQUENTIAL_FILE_VIEW_TODORENAME
#pragma once
//#include "dxl.hpp"
#include "ALib.EnumRecords.H"
#include "ALib.App.CLI.H"
 
#if !defined(_WIN32)
  #include <unistd.h>
#endif
 
 
namespace dxl {
 
/// Todox: ai-generated.
/// RAII file-to-memory loader with optional mmap backend.
///
/// This class loads a file into memory and provides a stable pointer + length.
///
/// Backend options:
/// - Portable "read-all" into an internal buffer (always available).
/// - Optional mmap mapping on non-Windows builds
///
/// \warning Performance note:
/// This class is designed for *sequential* processing of the returned data.
/// For best results (especially with mmap + MADV_SEQUENTIAL), treat `data()`
/// as a forward-only byte stream: read from begin to end without repeated
/// random jumps backwards/forwards.
///
/// todos:
/// - move to alib::files
/// - change exceptions to ALib or don't throw even.
/// - use with classes TextFile and TextFileLineReader. Those are using
///      std::basic_istream<CharT,Traits>::getline
///   and that's quite slow
/// - add option to switch between MADV_SEQUENTIAL and MADV_WILLNEED
///   
class MappedFile {
  public:
    /// A minimal sequential-only cursor over the file data.
    /// Enforces the "forward-only" usage pattern in calling code.
    class Data {
      protected:
        const std::byte* p  ; ///< Current pointer position.
        const std::byte* end; ///< Pointer to the end of the data.
 
      public:
        /// Defaulted default-constructor.
        Data()                                                         : p(nullptr), end(nullptr) {}
 
        /// Constructor.
        /// @param pData Pointer to the start of the data.
        /// @param n     Size of the data in bytes.
        Data(const std::byte* pData, std::size_t n) : p(pData), end(p + n) {}
 
        /// Remaining bytes.
        /// @return The number of bytes from current position to end.
        std::size_t Remaining() const noexcept { return static_cast<std::size_t>(end - p); }
 
        /// True if at end.
        /// @return \c true if the current position reached #end, \c false otherwise.
        bool IsEOF() const noexcept { return p >= end; }
 
        /// Get the next byte and advance.
        ///
        /// @tparam TCheck  Defaults to #alib::CHK, which is the normal invocation mode.
        ///                 If #alib::NC is given, no range check is performed.
        ///                 In debug builds, an assertion is raised if the cursor is at end.
        /// @return The byte at current position.
        template <typename TCheck = alib::CHK>
        std::byte Next() {
            if constexpr ( TCheck::value ) {
                if (p>= end) return std::byte{0};
            } else
                ALIB_ASSERT_ERROR( p < end, "DXL", "NC-Data::Next: @ end." )
 
            return *p++;
        }
 
        /// Get the next byte as a \b char and advance.
        ///
        /// @tparam TCheck  Defaults to #alib::CHK, which is the normal invocation mode.
        ///                 If #alib::NC is given, no range check is performed.
        ///                 In debug builds, an assertion is raised if the cursor is at end.
        /// @return The byte at current position.
        template <typename TCheck = alib::CHK>
        char operator()() {
            if constexpr ( TCheck::value ) {
                if (p>= end) return char{0};
            } else
                ALIB_ASSERT_ERROR( p < end, "DXL", "NC-Data::Next: @ end." )
 
            return char(*p++);
        }
 
        /// Get pointer to current position (read-only).
        /// @return Pointer to current position.
        const std::byte* Current() const noexcept { return p; }
 
        /// Advance by n bytes (must stay within range).
        ///
        /// @tparam TCheck  Defaults to #alib::CHK, which is the normal invocation mode.
        ///                 If #alib::NC is given, no range check is performed.
        ///                 In debug builds, an assertion is raised if advancing past end.
        /// @param n Number of bytes to advance.
        /// @throws std::out_of_range if advancing past end and \p{TCheck} is #alib::CHK.
        template <typename TCheck = alib::CHK>
        void            Skip(std::size_t n) {
            if constexpr ( TCheck::value ) {
                if (n > Remaining()) throw std::out_of_range("Data advance past end");
            } else
                ALIB_ASSERT_ERROR( n <= Remaining(), "DXL", "NC-Data::Skip: past end." )
            p += n;
        }
    };
 
  protected:
    std::size_t             size        = 0;       ///< Size of the loaded data.
    std::vector<std::byte>  noMMapBuf;             ///< Internal buffer used for fallback read mode.
    #if defined(_POSIX_MAPPED_FILES) && _POSIX_MAPPED_FILES > 0
        void*               mapAddr     = nullptr; ///< Address of the memory-mapped region.
    #endif
 
  public:
    /// Default constructor. Creates an empty view.
    MappedFile() = default;
 
    /// Construct and load a file.
    /// @param path       File path.
    /// @param knownSize  File size in bytes if known. Defaults to \c max(), which
    ///                   triggers size detection.
    /// @param preferMmap If true, tries mmap first (when supported), else uses ReadAll.
    ///
    /// @throws std::runtime_error on failure to open/read/map the file.
    MappedFile( const char* path, std::size_t knownSize= std::numeric_limits<std::size_t>::max(),
                bool preferMmap = true)
    { Open(path, knownSize, preferMmap); }
 
    MappedFile(const MappedFile&)           = delete; ///< Deleted copy constructor.
    MappedFile(MappedFile&&)                = delete; ///< Deleted move constructor.
    MappedFile& operator=(const MappedFile&)= delete; ///< Deleted copy assignment operator.
    MappedFile& operator=(MappedFile&& )    = delete; ///< Deleted assignment operator.
                                                      ///< @return Void (deleted).
    ~MappedFile()                       { Close(); }  ///< Destructor. Calls #Close.
 
    /// Load a file (replaces previous contents).
    /// @param path        The file's path.
    /// @param knownSize   File size in bytes if known. Defaults to \c max() , which
    ///                    triggers size detection.
    /// @param disableMMap If \c true, skips \e mmap mode and uses standard read methods.
    ///
    /// @throws std::runtime_error on failure to open/read/map the file.
    /// @return A #Data object.
    Data                Open( const char* path,
                              std::size_t knownSize= std::numeric_limits<std::size_t>::max(),
                              bool disableMMap = false);
 
    /// Release resources (unmap / free buffer).
    void                Close() noexcept;
 
    /// @return \c true if the file was read with \e mmap mode, \c false otherwise.
    bool                IsMMap() const noexcept      { return mapAddr != nullptr; }
 
    /// @return File size in bytes.
    std::size_t         Size() const noexcept { return size; }
 
    /// @return \c true if the view is empty.
    bool                IsEmpty() const noexcept { return size == 0; }
};
 
 
 
} //namespace [dxl]
 
#endif // HPP_DXL_SEQUENTIAL_FILE_VIEW_TODORENAME