mmap.hpp

Go to the documentation of this file.

/* Copyright 2017 https://github.com/mandreyel
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this
 * software and associated documentation files (the "Software"), to deal in the Software
 * without restriction, including without limitation the rights to use, copy, modify,
 * merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to the following
 * conditions:
 *
 * The above copyright notice and this permission notice shall be included in all copies
 * or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
 * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
/*
 * Copyright 2026 Maxtek Consulting
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
 
#ifndef MIO_MMAP_HPP
#define MIO_MMAP_HPP
 
#include "mio/page.hpp"
 
#include <iterator>
#include <string>
#include <system_error>
#include <cstdint>
 
#ifdef _WIN32
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#else
#define INVALID_HANDLE_VALUE -1
#endif
 
namespace mio {
 
// This value may be provided as the `length` parameter to the constructor or
// `map`, in which case a memory mapping of the entire file is created.
enum
{
    map_entire_file = 0
};
 
#ifdef _WIN32
using file_handle_type = HANDLE;
#else
using file_handle_type = int;
#endif
 
// This value represents an invalid file handle type. This can be used to
// determine whether `basic_mmap::file_handle` is valid, for example.
const static file_handle_type invalid_handle = INVALID_HANDLE_VALUE;
 
template <access_mode AccessMode, typename ByteT>
struct basic_mmap
{
    using value_type             = ByteT;
    using size_type              = size_t;
    using reference              = value_type&;
    using const_reference        = const value_type&;
    using pointer                = value_type*;
    using const_pointer          = const value_type*;
    using difference_type        = std::ptrdiff_t;
    using iterator               = pointer;
    using const_iterator         = const_pointer;
    using reverse_iterator       = std::reverse_iterator<iterator>;
    using const_reverse_iterator = std::reverse_iterator<const_iterator>;
    using iterator_category      = std::random_access_iterator_tag;
    using handle_type            = file_handle_type;
 
    static_assert(sizeof(ByteT) == sizeof(char), "ByteT must be the same size as char.");
 
private:
    // Points to the first requested byte, and not to the actual start of the mapping.
    pointer data_ = nullptr;
 
    // Length--in bytes--requested by user (which may not be the length of the
    // full mapping) and the length of the full mapping.
    size_type length_        = 0;
    size_type mapped_length_ = 0;
 
    // Letting user map a file using both an existing file handle and a path
    // introcudes some complexity (see `is_handle_internal_`).
    // On POSIX, we only need a file handle to create a mapping, while on
    // Windows systems the file handle is necessary to retrieve a file mapping
    // handle, but any subsequent operations on the mapped region must be done
    // through the latter.
    handle_type file_handle_ = INVALID_HANDLE_VALUE;
#ifdef _WIN32
    handle_type file_mapping_handle_ = INVALID_HANDLE_VALUE;
#endif
 
    // Letting user map a file using both an existing file handle and a path
    // introcudes some complexity in that we must not close the file handle if
    // user provided it, but we must close it if we obtained it using the
    // provided path. For this reason, this flag is used to determine when to
    // close `file_handle_`.
    bool is_handle_internal_;
 
public:
    basic_mmap()
            : is_handle_internal_(true) {};
 
#ifdef __cpp_exceptions
    template <typename String>
    explicit basic_mmap(const String& path, const size_type& offset = 0,
                        const size_type& length = map_entire_file) {
        std::error_code error;
        map(path, offset, length, error);
        if(error) {
            throw std::system_error(error);
        }
    }
 
    explicit basic_mmap(const handle_type& handle, const size_type& offset = 0,
                        const size_type& length = map_entire_file) {
        std::error_code error;
        map(handle, offset, length, error);
        if(error) {
            throw std::system_error(error);
        }
    }
#endif // __cpp_exceptions
 
    basic_mmap(const basic_mmap&) = delete;
    basic_mmap(basic_mmap&&);
    basic_mmap& operator=(const basic_mmap&) = delete;
    basic_mmap& operator=(basic_mmap&&);
 
    ~basic_mmap();
 
    handle_type file_handle() const noexcept { return file_handle_; }
    handle_type mapping_handle() const noexcept;
 
    bool is_open() const noexcept { return file_handle_ != invalid_handle; }
 
    bool empty() const noexcept { return length() == 0; }
 
    bool is_mapped() const noexcept;
 
    size_type size() const noexcept { return length(); }
    size_type length() const noexcept { return length_; }
    size_type mapped_length() const noexcept { return mapped_length_; }
 
    size_type mapping_offset() const noexcept { return mapped_length_ - length_; }
 
    template <access_mode A = AccessMode,
              typename      = typename std::enable_if<A == access_mode::write>::type>
    pointer data() noexcept {
        return data_;
    }
    const_pointer data() const noexcept { return data_; }
 
    template <access_mode A = AccessMode,
              typename      = typename std::enable_if<A == access_mode::write>::type>
    iterator begin() noexcept {
        return data();
    }
    const_iterator begin() const noexcept { return data(); }
    const_iterator cbegin() const noexcept { return data(); }
 
    template <access_mode A = AccessMode,
              typename      = typename std::enable_if<A == access_mode::write>::type>
    iterator end() noexcept {
        return data() + length();
    }
    const_iterator end() const noexcept { return data() + length(); }
    const_iterator cend() const noexcept { return data() + length(); }
 
    template <access_mode A = AccessMode,
              typename      = typename std::enable_if<A == access_mode::write>::type>
    reverse_iterator rbegin() noexcept {
        return reverse_iterator(end());
    }
    const_reverse_iterator rbegin() const noexcept { return const_reverse_iterator(end()); }
    const_reverse_iterator crbegin() const noexcept { return const_reverse_iterator(end()); }
 
    template <access_mode A = AccessMode,
              typename      = typename std::enable_if<A == access_mode::write>::type>
    reverse_iterator rend() noexcept {
        return reverse_iterator(begin());
    }
    const_reverse_iterator rend() const noexcept { return const_reverse_iterator(begin()); }
    const_reverse_iterator crend() const noexcept { return const_reverse_iterator(begin()); }
 
    reference       operator[](const size_type& i) noexcept { return data_[i]; }
    const_reference operator[](const size_type& i) const noexcept { return data_[i]; }
 
    template <typename String>
    void map(const String& path, const size_type& offset, const size_type& length,
             std::error_code& error);
 
    template <typename String>
    void map(const String& path, std::error_code& error) {
        map(path, 0, map_entire_file, error);
    }
 
    void map(const handle_type& handle, const size_type& offset, const size_type& length,
             std::error_code& error);
 
    void map(const handle_type& handle, std::error_code& error) {
        map(handle, 0, map_entire_file, error);
    }
 
    void unmap();
 
    void swap(basic_mmap& other);
 
    template <access_mode A = AccessMode>
    typename std::enable_if<A == access_mode::write, void>::type sync(std::error_code& error);
 
private:
    template <access_mode A = AccessMode,
              typename      = typename std::enable_if<A == access_mode::write>::type>
    pointer get_mapping_start() noexcept {
        return !data() ? nullptr : data() - mapping_offset();
    }
 
    const_pointer get_mapping_start() const noexcept {
        return !data() ? nullptr : data() - mapping_offset();
    }
 
    template <access_mode A = AccessMode>
    typename std::enable_if<A == access_mode::write, void>::type
    conditional_sync(); // cppcheck-suppress functionStatic
    template <access_mode A = AccessMode>
    typename std::enable_if<A == access_mode::read, void>::type
    conditional_sync(); // cppcheck-suppress functionStatic
};
 
template <access_mode AccessMode, typename ByteT>
bool operator==(const basic_mmap<AccessMode, ByteT>& a, const basic_mmap<AccessMode, ByteT>& b);
 
template <access_mode AccessMode, typename ByteT>
bool operator!=(const basic_mmap<AccessMode, ByteT>& a, const basic_mmap<AccessMode, ByteT>& b);
 
template <access_mode AccessMode, typename ByteT>
bool operator<(const basic_mmap<AccessMode, ByteT>& a, const basic_mmap<AccessMode, ByteT>& b);
 
template <access_mode AccessMode, typename ByteT>
bool operator<=(const basic_mmap<AccessMode, ByteT>& a, const basic_mmap<AccessMode, ByteT>& b);
 
template <access_mode AccessMode, typename ByteT>
bool operator>(const basic_mmap<AccessMode, ByteT>& a, const basic_mmap<AccessMode, ByteT>& b);
 
template <access_mode AccessMode, typename ByteT>
bool operator>=(const basic_mmap<AccessMode, ByteT>& a, const basic_mmap<AccessMode, ByteT>& b);
 
template <typename ByteT>
using basic_mmap_source = basic_mmap<access_mode::read, ByteT>;
 
template <typename ByteT>
using basic_mmap_sink = basic_mmap<access_mode::write, ByteT>;
 
using mmap_source  = basic_mmap_source<char>;
using ummap_source = basic_mmap_source<unsigned char>;
 
using mmap_sink  = basic_mmap_sink<char>;
using ummap_sink = basic_mmap_sink<unsigned char>;
 
template <typename MMap, typename MappingToken>
MMap make_mmap(const MappingToken& token, int64_t offset, int64_t length, std::error_code& error) {
    MMap mmap;
    mmap.map(token, offset, length, error);
    return mmap;
}
 
template <typename MappingToken>
mmap_source make_mmap_source(const MappingToken& token, mmap_source::size_type offset,
                             mmap_source::size_type length, std::error_code& error) {
    return make_mmap<mmap_source>(token, offset, length, error);
}
 
template <typename MappingToken>
mmap_source make_mmap_source(const MappingToken& token, std::error_code& error) {
    return make_mmap_source(token, 0, map_entire_file, error);
}
 
template <typename MappingToken>
mmap_sink make_mmap_sink(const MappingToken& token, mmap_sink::size_type offset,
                         mmap_sink::size_type length, std::error_code& error) {
    return make_mmap<mmap_sink>(token, offset, length, error);
}
 
template <typename MappingToken>
mmap_sink make_mmap_sink(const MappingToken& token, std::error_code& error) {
    return make_mmap_sink(token, 0, map_entire_file, error);
}
 
}; // namespace mio
 
#include "detail/mmap.ipp"
 
#endif // MIO_MMAP_HPP