Code/Engine/Foundation/IO/MemoryMappedFile.h - dev - redgpu/ezEngine

Code/Engine/Foundation/IO/MemoryMappedFile.h
74 строки3 KB
Jan Krassnigg
Improved documentation of the Foundation library (#1664)
20 сен 2025, 19:53
20 сен 2025, 19:530e28096
#pragma once

#include <Foundation/Types/UniquePtr.h>

struct ezMemoryMappedFileImpl;

/// \brief Platform-abstracted interface for memory-mapped file I/O and shared memory access
///
/// Provides efficient file access by mapping files directly into virtual memory, eliminating
/// the need for explicit read/write operations. Particularly beneficial for large files where
/// random access patterns would cause excessive disk I/O with traditional file operations.
/// Also supports creating shared memory regions for inter-process communication.
///
/// Memory mapping allows the OS to handle paging and caching automatically, improving performance
/// for scenarios like asset loading, database files, or large data processing pipelines.
class EZ_FOUNDATION_DLL ezMemoryMappedFile
{
  EZ_DISALLOW_COPY_AND_ASSIGN(ezMemoryMappedFile);

public:
  ezMemoryMappedFile();
  ~ezMemoryMappedFile();

  enum class Mode
  {
    None,      ///< Currently no file is mapped
    ReadOnly,  ///< File is mapped for read-only access
    ReadWrite, ///< File is mapped for read/write access
  };

  /// \brief The start point for interpreting byte offsets into the memory
  enum class OffsetBase
  {
    Start, ///< Byte offsets are relative to the start of the mapped memory
    End,   ///< Byte offsets are relative to the end of the mapped memory. Increasing positive values go towards the start
           ///< of the memory.
  };

#if EZ_ENABLED(EZ_SUPPORTS_MEMORY_MAPPED_FILE) || defined(EZ_DOCS)
  /// \brief Attempts to open the given file and map it into memory
  ///
  /// \param szAbsolutePath must be an absolute path to the file that should be mapped.
  ///        The file also must exist and have a size larger than zero bytes.
  /// \param mode How to map the file into memory.
  ezResult Open(ezStringView sAbsolutePath, Mode mode);
#endif

#if EZ_ENABLED(EZ_SUPPORTS_SHARED_MEMORY) || defined(EZ_DOCS)
  /// \brief Attempts to open or create the given shared memory block addressed by szSharedName
  ///
  /// \param szSharedName The name of the shared memory region.
  /// \param uiSize The size of the memory which should be mapped.
  /// \param mode How to map the file into memory.
  ezResult OpenShared(ezStringView sSharedName, ezUInt64 uiSize, Mode mode);
#endif

  /// \brief Removes the memory mapping. Outstanding modifications will be written back to disk at this point.
  void Close();

  /// \brief Returns the mode with which the file was opened or None, if is currently not in use.
  Mode GetMode() const;

  /// \brief Returns the size (in bytes) of the memory mapping. Zero if no file is mapped at the moment.
  ezUInt64 GetFileSize() const;

  /// \brief Returns a pointer for reading the mapped file. Asserts that the memory mapping was done successfully.
  const void* GetReadPointer(ezUInt64 uiOffset = 0, OffsetBase base = OffsetBase::Start) const;

  /// \brief Returns a pointer for writing the mapped file. Asserts that the memory mapping was successful and the mode was ReadWrite.
  void* GetWritePointer(ezUInt64 uiOffset = 0, OffsetBase base = OffsetBase::Start);

private:
  ezUniquePtr<ezMemoryMappedFileImpl> m_pImpl;
};