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
}

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