mmap_reader.hpp

Go to the documentation of this file.

#pragma once
 
// MemoryMappedAudioReader — zero-copy audio file access via memory mapping.
// Combines MemoryMappedFile with codec decoding for efficient large-file access.
 
#include <limits>
#include <memory>
#include <optional>
#include <pulp/audio/audio_file.hpp>
#include <pulp/runtime/memory_mapped_file.hpp>
#include <string>
#include <string_view>
 
namespace pulp::audio {

class MemoryMappedAudioReader {
  public:
    // All special members are out-of-line (defined in the .cpp where RangedState
    // is complete) — the pimpl unique_ptr requires a complete type for
    // construction-cleanup, destruction, and move.
    MemoryMappedAudioReader();
    ~MemoryMappedAudioReader();
    MemoryMappedAudioReader(MemoryMappedAudioReader&&) noexcept;
    MemoryMappedAudioReader& operator=(MemoryMappedAudioReader&&) noexcept;

    bool open(std::string_view path);
    bool open(std::string_view path, std::size_t maximum_mapped_bytes);

    void close();

    bool is_open() const;

    const AudioFileInfo& info() const {
        return info_;
    }

    bool read_frames(float** dest_channels, uint32_t num_channels, uint64_t start_frame,
                     uint64_t num_frames);

    bool read_frames_ranged_only(float** dest_channels, uint32_t num_channels, uint64_t start_frame,
                                 uint64_t num_frames);

    bool supports_ranged_read() const;

    std::optional<AudioFileData> read_all();

    const uint8_t* data() const;
    size_t size() const;

    bool copy_access_policy_to(std::string_view destination) const noexcept;
    runtime::AccessPolicyTarget
    prepare_access_policy_target(std::string_view destination) const noexcept;
    bool path_refers_to_open_file(std::string_view path) const noexcept;
    runtime::FileIdentity opened_file_identity() const noexcept;
 
  private:
    // Ranged (seek-based) decoder state over the mapped bytes; nullptr when the
    // active format can't be range-read (read_frames then decode-once-caches).
    // BackingState retains the original source handle for identity/access-policy
    // operations and owns an immutable temporary snapshot used for all reads.
    struct BackingState;
    struct RangedState;
 
    std::unique_ptr<BackingState> backing_;
    AudioFileInfo info_;
    std::string path_;
    std::unique_ptr<RangedState> ranged_;
 
    bool read_frames_impl(float** dest_channels, uint32_t num_channels, uint64_t start_frame,
                          uint64_t num_frames, bool allow_whole_file_fallback);
};
 
} // namespace pulp::audio