Memory-Mapped Files

Overview

Acknowledgments

Installation

Headers

Reference

1. Class mapped_file_params
2. Class mapped_file_source
3. Class mapped_file_sink
4. Class mapped_file

Overview

The classes mapped_file_source, mapped_file_sink and mapped_file provide access to memory-mapped files on Windows and POSIX systems. These Devices behave much like the File Wrappers basic_file_source, basic_file_sink and basic_file, with the following important differences:

• By default, files must exist before being opened, and are not truncated; attempting to write past the end of a file results in an error. To map a file which does not yet exist, use mapped_file_params::new_file_size.
• Files are always opened in binary mode.
• Wide-character streams are not supported.

Wide-character versions of the memory-mapped file Devices may be defined as follows, using the template code_converter:

    #include <boost/iostreams/code_converter.hpp>
    #include <boost/iostreams/maped_file.hpp>

    typedef code_converter<mapped_file_source>  wmapped_file_source;
    typedef code_converter<mapped_file_sink>    wmapped_file_sink;

Acknowledgments

The memory-mapped file Devices are based on the work of Craig Henderson ([Henderson]). Additionals features were implemented by Jonathan Graehl.

Installation

The memory-mapped file Devices depend on the source file <libs/iostreams/src/mapped_file.cpp>. This source file makes use of Windows or POSIX headers depending on the user's operating system. For installation instructions see Installation.

Headers

<boost/iostreams/device/mapped_file.hpp>

Reference

1. Class mapped_file_params

Description

Class encapsulating the parameters used to open a memory-mapped file.

Synopsis

namespace boost { namespace iostreams {

struct mapped_file_params {
    explicit mapped_file_params();
    explicit mapped_file_params(const std::string& path);
    std::string              path;
    std::ios_base::openmode  mode;
    stream_offset            offset;
    std::size_t              length;
    stream_offset            new_file_size;
    const char*              hint;
};

} } // End namespace boost::io

mapped_file_params::path

    std::string              path;

The pathname of the file to map.

mapped_file_params::mode

    std::ios_base::openmode  mode;

Indicates whether the file should be opened with read-access, write-access or both. Ignored by mapped_file_source and mapped_file_sink .

mapped_file_params::offset

    stream_offset            offset;

The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be abotained via the static member function alignment of mapped_file_source, mapped_file_sink or mapped_file. Defaults to 0.

mapped_file_params::length

    std::size_t              length;

The number of bytes to map. If this parameter is not specified, the entire file is mapped.

mapped_file_params::new_file_size

    stream_offset            new_file_size;

If this value is non-zero it specifies the size of a file to be created. If a file with pathname path already exists, it will be overwritten.

mapped_file_params::hint

    const char*              hint;

Suggests a location in the process's address space for the mapping to begin.

2. Class mapped_file_source

Description

Model of Source providing read-only access to memory-mapped files on Windows and POSIX systems.

Synopsis

namespace boost { namespace iostreams {

class mapped_file_source {
public:
    typedef char                      char_type;
    typedef [implementation-defined]  category;
    mapped_file_source();
    explicit mapped_file_source(mapped_file_params params);
    explicit mapped_file_source( const std::string& path,
                                 size_type length = max_length,
                                 boost::intmax_t offset = 0 );
    void open(mapped_file_params params);
    void open( const std::string& path,
               size_type length = max_length,
               boost::intmax_t offset = 0 );
    bool is_open() const;
    void close();
    size_type size() const;
    const char* data() const;
    static int alignment();
};

} } // End namespace boost::io

mapped_file_source::mapped_file_source

    mapped_file_source();

Constructs a mapped_file_source which must be opened before it can be used to perform i/o.

    explicit mapped_file_source(mapped_file_params params);

Constructs a mapped_file_source from the given parameters.

    explicit mapped_file_source( const std::string& path,
                                 size_type length = max_length,
                                 boost::intmax_t offset = 0 );

Constructs a mapped_file_source to access a specified file. The parameters have the following interpretation:

mapped_file_source::open

    void open(mapped_file_params params);

Connects this mapped_file_source to a memory-mapped file obtained as described by the given parameters.

        void open( const std::string& path,
                   size_type length = max_length,
                   boost::intmax_t offset = 0 );

Connects this mapped_file_source to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:

mapped_file_source::is_open

    bool is_open() const;

Returns true if this mapped_file_source has been successfully opened without subsequently having been closed.

mapped_file_source::close

    void close();

Frees the mapping associated with this mapped_file_source.

mapped_file_source::size

    size_type size() const;

Returns the size in bytes of the mapping associated with this mapped_file_source.

mapped_file_source::data

    const char* data() const;

Returns a pointer to the first byte of data in the mapping associated with this mapped_file_source.

mapped_file_source::alignment

    static int alignment();

Returns the operating system's virtual memory allocation granularity.

3. Class mapped_file_sink

Description

Model of Sink providing write-only access to memory-mapped files on Windows and POSIX systems.

Synopsis

namespace boost { namespace iostreams {

class mapped_file_sink {
public:
    typedef char                      char_type;
    typedef [implementation-defined]  category;
    mapped_file_sink();
    explicit mapped_file_sink(mapped_file_params params);
    explicit mapped_file_sink( const std::string& path,
                               size_type length = max_length,
                               boost::intmax_t offset = 0 );
    void open(mapped_file_params params);
    void open( const std::string& path,
               size_type length = max_length,
               boost::intmax_t offset = 0 );
    bool is_open() const;
    void close();
    size_type size() const;
    char* data() const;
    static int alignment();
};

} } // End namespace boost::io

mapped_file_sink::mapped_file_sink

    mapped_file_sink();

Constructs a mapped_file_sink which must be opened before it can be used to perform i/o.

    explicit mapped_file_sink(mapped_file_params params);

Constructs a mapped_file_sink from the given parameters.

    explicit mapped_file_sink( const std::string& path,
                               size_type length = max_length,
                               boost::intmax_t offset = 0 );

Constructs a mapped_file_sink to access a specified file. The parameters have the following interpretation:

mapped_file_sink::open

    void open(mapped_file_params params);

Connects this mapped_file_sink to a memory-mapped file obtained as described by the given parameters.

        void open( const std::string& path,
                   size_type length = max_length,
                   boost::intmax_t offset = 0 );

Connects this mapped_file_sink to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:

mapped_file_sink::is_open

    bool is_open() const;

Returns true if this mapped_file_sink has been successfully opened without subsequently having been closed.

mapped_file_sink::close

    void close();

Frees the mapping associated with this mapped_file_sink.

mapped_file_sink::size

    size_type size() const;

Returns the size in bytes of the mapping associated with this mapped_file_sink.

mapped_file_sink::data

    char* data() const;

Returns a pointer to the first byte of data in the mapping associated with this mapped_file_sink.

mapped_file_sink::alignment

    static int alignment();

Returns the operating system's virtual memory allocation granularity.

4. Class mapped_file

Description

Model of SeekableDevice providing read-write access to memory-mapped files on Windows and POSIX systems.

Synopsis

namespace boost { namespace iostreams {

class mapped_file {
public:
    typedef char                      char_type;
    typedef [implementation-defined]  category;
    mapped_file();
    explicit mapped_file(mapped_file_params params);
    explicit mapped_file( const std::string& path,
                          std::ios_base::openmode mode =
                              std::ios_base | std::ios_base,
                          size_type length = max_length,
                          boost::intmax_t offset = 0 );
    void open(mapped_file_params params);
    void open( const std::string& path,
               std::ios_base::openmode mode = 
                   std::ios_base | std::ios_base,
               size_type length = max_length,
               boost::intmax_t offset = 0 );
    bool is_open() const;
    void close();
    size_type size() const;
    char* data() const;
    const char* const_data() const;
    static int alignment();
};

} } // End namespace boost::io

mapped_file::mapped_file

    mapped_file();

Constructs a mapped_file which must be opened before it can be used to perform i/o.

    explicit mapped_file(mapped_file_params params);

Constructs a mapped_file from the given parameters.

    explicit mapped_file( const std::string& path,
                          std::ios_base::openmode mode = 
                              std::ios_base | std::ios_base,
                          size_type length = max_length,
                          boost::intmax_t offset = 0 );

Constructs a mapped_file to access a specified file. The parameters have the following interpretation:

mapped_file::open

    void open(mapped_file_params params);

Connects this mapped_file to a memory-mapped file obtained as described by the given parameters.

        void open( const std::string& path,
                   std::ios_base::openmode mode = 
                       std::ios_base | std::ios_base,
                   size_type length = max_length,
                   boost::intmax_t offset = 0 );

Connects this mapped_file to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:

mapped_file::is_open

    bool is_open() const;

Returns true if this mapped_file has been successfully opened without subsequently having been closed.

mapped_file::close

    void close();

Frees the mapping associated with this mapped_file.

mapped_file::size

    size_type size() const;

Returns the size in bytes of the mapping associated with this mapped_file.

mapped_file::data

    char* data() const;

Returns a pointer to the first byte of data in the mapping associated with this mapped_file, if it was opened with write-access, and a null pointer otherwise.

mapped_file::data

    const char* const_data() const;

Returns a pointer to the first byte of data in the mapping associated with this mapped_file.

mapped_file::alignment

    static int alignment();

Returns the operating system's virtual memory allocation granularity.

Revised 20 May, 2004

© Copyright Jonathan Turkanis, 2004

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)