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:
mapped_file_params::new_file_size.
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;
The memory-mapped file Devices are based on the work of Craig Henderson ([Henderson]). Additionals features were implemented by Jonathan Graehl.
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.
<boost/iostreams/device/mapped_file.hpp>mapped_file_paramsClass encapsulating the parameters used to open a memory-mapped file.
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::pathstd::string path;
The pathname of the file to map.
mapped_file_params::modestd::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::offsetstream_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::lengthstd::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_sizestream_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::hintconst char* hint;
Suggests a location in the process's address space for the mapping to begin.
mapped_file_sourceModel of Source providing read-only access to memory-mapped files on Windows and POSIX systems.
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_sourcemapped_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:
| path | - | The pathname of the file to map. |
| length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped. |
| 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 obtained using the static member function alignment. |
mapped_file_source::openvoid 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:
| path | - | The pathname of the file to map. |
| length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped. |
| 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 obtained using the static member function alignment. |
mapped_file_source::is_openbool 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::dataconst char* data() const;
Returns a pointer to the first byte of data in the mapping associated with this mapped_file_source.
mapped_file_source::alignmentstatic int alignment();
Returns the operating system's virtual memory allocation granularity.
mapped_file_sinkModel of Sink providing write-only access to memory-mapped files on Windows and POSIX systems.
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_sinkmapped_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:
| path | - | The pathname of the file to map. |
| length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped. |
| 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 obtained using the static member function alignment. |
mapped_file_sink::openvoid 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:
| path | - | The pathname of the file to map. |
| length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped. |
| 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 obtained using the static member function alignment. |
mapped_file_sink::is_openbool 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::datachar* data() const;
Returns a pointer to the first byte of data in the mapping associated with this mapped_file_sink.
mapped_file_sink::alignmentstatic int alignment();
Returns the operating system's virtual memory allocation granularity.
mapped_fileModel of SeekableDevice providing read-write access to memory-mapped files on Windows and POSIX systems.
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_filemapped_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:
| path | - | The pathname of the file to map. |
| mode | - | Indicates whether the file should be opened with read-access, write-access or both. |
| length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped. |
| 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 obtained using the static member function alignment. |
mapped_file::openvoid 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:
| path | - | The pathname of the file to map. |
| mode | - | Indicates whether the file should be opened with read-access, write-access or both. |
| length | - | The number of bytes to map. If this parameter is not specified, the entire file is mapped. |
| 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 obtained using the static member function alignment. |
mapped_file::is_openbool 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::datachar* 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::dataconst char* const_data() const;
Returns a pointer to the first byte of data in the mapping associated with this mapped_file.
mapped_file::alignmentstatic 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)