class io.MappedFile
Overview
This class provides high level mapped access to the contents of regular disk files. More…
import "io_base.jncx" import "io_MappedFile.jnc" class MappedFile { // fields bool readonly m_isOpen; // properties size_t autoget property m_dynamicViewLimit; uint64_t const property m_size; // construction construct(); destruct(); // methods bool errorcode open( string_t name, io.FileOpenFlags flags = 0 ); void close(); bool errorcode setSize(uint64_t size); void* errorcode view( uint64_t offset, size_t size, bool isPermanent = false ); void unmapAllViews(); // aliases alias dispose = close; };
Detailed Documentation
This class provides high level mapped access to the contents of regular disk files.
From the programmer’s point of view, io.MappedFile
exposes the most
natural interface imaginable. You just tell: I want to access a region of
the file at this offset, and of this length. And you get a pointer to
this region(or null
if this could not be done). That’s it! Actual
mapping operations, aligning offsets and maintaining a database of
previously mapped views is happening behind the stage.
Views provided by io.MappedFile
can be permanent or dynamic.
A pointer to a permanent view, as the name suggests, remains valid all the
time while the file is open. Pointers to dynamic views, on the other
hand, do expire. You can only access m_dynamicViewLimit
views at the
same time. Expiration queue is organized in FIFO(first-in-first-out)
manner, but it is readjusted each time user requests access to the region
with view
method(last accessed view is moved to the tail of the
expiration queue).
Sample code:
struct Hdr { uint32_t m_signature; uint32_t m_version; uint32_t m_sectionCount; // ... } struct SectionDesc { uint64_t m_offset; uint64_t m_size; } void foo(string_t fileName) { disposable io.MappedFile file; file.open(fileName, io.FileOpenFlags.ReadOnly); // permanent view of header Hdr const* hdr = file.view(0, sizeof(Hdr), true); size_t offset = sizeof(Hdr); for ( size_t i = 0; i < hdr.m_sectionCount; i++, offset += sizeof(SectionDesc) ) { SectionDesc const* sectionDesc = file.view( offset, sizeof(SectionDesc) ); void const* section = file.view( sectionDesc.m_offset, sectionDesc.m_size ); // ... } catch: // handle error }
See also:
Fields
bool readonly m_isOpen
Holds the open status for the mapped file, i.e. true
if opened;
false
otherwise.
Properties
size_t autoget property m_dynamicViewLimit
Holds the maximum amount of dynamic views maintained in
io.MappedFile
internal database. Once dynamic view limit is
exhausted, the dynamic view which has not been accessed the longest,
is unmapped and released.
The required amount of dynamic view limit, of course, depends on the particular algorithm used to access regions of the file – i.e. how many regions you need to access simultaneously.
uint64_t const property m_size
This property is used for getting and setting file size.
Reading from this property returns current size of the file; writing to it sets new size. If setting new size fails, IO error supplied by operating system is set; then dynamic exception is thrown.
Methods
bool errorcode open( string_t name, io.FileOpenFlags flags = 0 )
Opens or creates a file, but no mappings are created.
The function accepts two arguments. The first one, name
specifies
the name of the file/device. The second one, flags
, can be used to
specify open options. Check io.FileOpenFlags
for the complete list of
options.
If file could not be opened, IO error supplied by operating system is
set and then the function returns false
[1].
void close()
Closes a previously opened file, does nothing if the file is not opened. This function always succeeds.
Sometimes it may be convenient to use disposable pattern to ensure
timely invokation of close
[2].
void* errorcode view( uint64_t offset, size_t size, bool isPermanent = false )
Provides access to the region of the file at offset
and size
bytes long. The final, third argument is used to specify whether the
requested view should be permanent or dynamic.
Returns a pointer to the requested region, or null
if mapping
operation failed [1].
Aliases
alias dispose = close
Effectively makes io.MappedFile
a disposable class [2].
Footnotes