ContextQMD
Back to Arangodb

Memory-Mapped Files

3rdParty/boost/1.78.0/libs/iostreams/doc/classes/mapped_file.html

3.12.9.121.9 KB
Original Source

Memory-Mapped Files

OverviewAcknowledgmentsInstallationHeadersReference

  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\>](../../../../boost/iostreams/code_converter.hpp)#include[\<boost/iostreams/device/mapped\_file.hpp\>](../../../../boost/iostreams/device/mapped_file.hpp)typedefcode_converter<mapped_file_source>wmapped\_file\_source;typedefcode_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

namespaceboost {namespaceiostreams {structmapped\_file\_params{explicitmapped_file_params();explicitmapped_file_params(conststd::string& path);
    std::string[path](#mapped_file_params_hint);
    mapped_file::mapmode[flags](#mapped_file_params_flags);
    std::ios_base::openmode[mode](#mapped_file_params_mode); // Deprecated
    stream_offset[offset](#mapped_file_params_offset);
    std::size_t[length](#mapped_file_params_length);
    stream_offset[new\_file\_size](#mapped_file_params_size);constchar*[hint](#mapped_file_params_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. This member is deprecated. Please use flags in new code instead.

mapped_file_params::flags

mapped_file::mapmode flags;

Indicates whether the file should be opened with read-access, read-write-access, or private access. A file opened with private access can be written to, but the changes will not affect the underlying file.

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

constchar* 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

namespaceboost {namespaceiostreams {classmapped\_file\_source{public:typedefcharchar_type;typedef[implementation-defined]category;[mapped\_file\_source](#mapped_file_source_default_ctor)();explicit[mapped\_file\_source](#mapped_file_source_params_ctor)([mapped\_file\_params](#mapped_file_params)params);explicit[mapped\_file\_source](#mapped_file_source_basic_ctor)(conststd::string& path,
                                 size_type length = max_length,
                                 boost::intmax_t offset =0);
    void[open](#mapped_file_source_params_open)([mapped\_file\_params](#mapped_file_params)params);
    void[open](#mapped_file_source_basic_open)(conststd::string& path,
               size_type length = max_length,
               boost::intmax_t offset =0);bool[is\_open](#mapped_file_source_is_open)()const;void[close](#mapped_file_source_close)();
    size_type[size](#mapped_file_source_size)()const;constchar*[data](#mapped_file_source_data)()const;
    iterator[begin](#mapped_file_source_begin)()const;
    iterator[end](#mapped_file_source_end)()const;staticint[alignment](#mapped_file_source_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.

explicitmapped_file_source([mapped\_file\_params](#mapped_file_params)params);

Constructs a mapped_file_source from the given parameters.

explicitmapped_file_source(conststd::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::open

void open([mapped\_file\_params](#mapped_file_params)params);

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

void open(conststd::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_open

boolis_open()const;

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

mapped_file_source::close

voidclose();

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

constchar* data()const;

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

mapped_file_source::begin

iterator begin()const;

Returns an iterator to the first byte of data in the mapping associated with this mapped_file_source.

mapped_file_source::end

iterator end()const;

Returns an iterator to just past the last byte of data in the mapping associated with this mapped_file_source.

mapped_file_source::alignment

staticintalignment();

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

namespaceboost {namespaceiostreams {classmapped\_file\_sink{public:typedefcharchar_type;typedef[implementation-defined]category;enummapmode { readwrite, priv };[mapped\_file\_sink](#mapped_file_sink_default_ctor)();explicit[mapped\_file\_sink](#mapped_file_sink_params_ctor)([mapped\_file\_params](#mapped_file_params)params);explicit[mapped\_file\_sink](#mapped_file_sink_basic_ctor)(conststd::string& path,
                               size_type length = max_length,
                               boost::intmax_t offset =0,
                               mapmode flags = readwrite );
    void[open](#mapped_file_sink_params_open)([mapped\_file\_params](#mapped_file_params)params);
    void[open](#mapped_file_sink_basic_open)(conststd::string& path,
               size_type length = max_length,
               boost::intmax_t offset =0,
               mapmode flags = readwrite );bool[is\_open](#mapped_file_sink_is_open)()const;
    mapmode[flags](#mapped_file_sink_flags)()const;void[close](#mapped_file_sink_close)();
    size_type[size](#mapped_file_sink_size)()const;char*[data](#mapped_file_sink_data)()const;
    iterator[begin](#mapped_file_sink_begin)()const;
    iterator[end](#mapped_file_sink_end)()const;staticint[alignment](#mapped_file_sink_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.

explicitmapped_file_sink([mapped\_file\_params](#mapped_file_params)params);

Constructs a mapped_file_sink from the given parameters.

explicitmapped_file_sink(conststd::string& path,
                               size_type length = max_length,
                               boost::intmax_t offset =0,
                               mapmode flags );

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. | | flags | - | Indicates whether the mapped_file_sink should be opened for read-write access or private access. |

mapped_file_sink::open

void open([mapped\_file\_params](#mapped_file_params)params);

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

void open(conststd::string& path,
                   size_type length = max_length,
                   boost::intmax_t offset =0mapmode flags );

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. | | flags | - | Indicates whether the mapped_file_sink should be opened for read-write access or private access. |

mapped_file_sink::is_open

boolis_open()const;

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

mapped_file_sink::flags

mapmode flags()const;

Indicates whether the mapped_file_sink was opened for read/write-access or private-access.

mapped_file_sink::close

voidclose();

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::begin

iterator begin()const;

Returns an iterator to the first byte of data in the mapping associated with this mapped_file_sink.

mapped_file_sink::end

iterator end()const;

Returns an iterator to just past the last byte of data in the mapping associated with this mapped_file_sink.

mapped_file_sink::alignment

staticintalignment();

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

namespaceboost {namespaceiostreams {classmapped\_file{public:typedefcharchar_type;typedef[implementation-defined]category;enummapmode { readonly, readwrite, priv };[mapped\_file](#mapped_file_default_ctor)();explicit[mapped\_file](#mapped_file_params_ctor)([mapped\_file\_params](#mapped_file_params)params);explicit[mapped\_file](#mapped_file_basic_ctor)(conststd::string& path,
                          std::ios_base::openmode mode =
                              std::ios_base::in | std::ios_base::out,
                          size_type length = max_length,
                          boost::intmax_t offset =0);explicit[mapped\_file](#mapped_file_mapmode_ctor)(conststd::string& path,
                          mapmode mode,
                          size_type length = max_length,
                          boost::intmax_t offset =0);void[open](#mapped_file_params_open)([mapped\_file\_params](#mapped_file_params)params);void[open](#mapped_file_basic_open)(conststd::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_mapmode_open)(conststd::string& path,
               mapmode mode,
               size_type length = max_length,
               boost::intmax_t offset =0);bool[is\_open](#mapped_file_is_open)()const;
    mapmode[flags](#mapped_file_flags)()const;void[close](#mapped_file_close)();
    size_type[size](#mapped_file_size)()const;char*[data](#mapped_file_data)()const;constchar*[const\_data](#mapped_file_const_data)()const;
    iterator[begin](#mapped_file_begin)()const;
    const_iterator[const\_begin](#mapped_file_const_begin)()const;
    iterator[end](#mapped_file_end)()const;
    const_iterator[const\_end](#mapped_file_const_end)()const;staticint[alignment](#mapped_file_alignment)();
};

} } // End namespace boost::iostreams

mapped_file::mapped_file

mapped_file();

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

explicitmapped_file([mapped\_file\_params](#mapped_file_params)params);

Constructs a mapped_file from the given parameters.

explicitmapped_file(conststd::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. Use of std::ios_base::openmode with mapped_file is deprecated. Please use mapmode instead in new code. | | 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. |

explicitmapped_file(conststd::string& path,
                          mapmode mode,
                          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, read/write-access or private-access. | | 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::open

void open([mapped\_file\_params](#mapped_file_params)params);

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

void open(conststd::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. Use of std::ios_base::openmode with mapped_file is deprecated. Please use mapmode in new code. | | 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. |

void open(conststd::string& path,
                   mapmode mode,
                   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, read/write-access or private access. | | 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_open

boolis_open()const;

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

mapped_file::flags

mapmode flags()const;

Indicates whether the mapped_file was opened for read-access, read/write-access or private-access.

mapped_file::close

voidclose();

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::const_data

constchar* const_data()const;

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

mapped_file::begin

iterator begin()const;

Returns an iterator 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 iterator otherwise.

mapped_file::const_begin

const_iterator const_begin()const;

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

mapped_file::end

iterator end()const;

Returns an iterator to just past the last 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::const_end

const_iterator const_end()const;

Returns a const_iterator to just past the last byte of data in the mapping associated with this mapped_file.

mapped_file::alignment

staticintalignment();

Returns the operating system's virtual memory allocation granularity.

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

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)