ost::MappedFile(3)

📦 version 1.8.1, in ubuntu jammy

💖 ost::MappedFile 💖

okay bestie, welcome to ost::MappedFile(3) — the manual page for the class that literally takes a disk file and yeets it into memory. no cap.

🌸 NAME 🌸

ost::MappedFile — create and map a disk file into memory. that's it, that's the whole job. iconic behavior honestly.

✨ SYNOPSIS ✨

#include <file.h>

Inherits ost::RandomFile.

🎀 Public Member Functions

  • MappedFile (const char *fname, Access mode) — open up a file so it can be mapped. 💅
  • MappedFile (const char *fname, Access mode, size_t size) — if it's not there yet, make it, then map a file of the size you asked for into memory. ✨
  • MappedFile (const char *fname, pos_t offset, size_t size, Access mode) — map a chunk of a file, or the whole thing, using the shared memory access mode you picked. 🦋
  • virtual ~MappedFile () — release a mapped section of memory that belongs to a file. bye babe 🫶
  • void sync (void) — sync the contents of the mapped memory chunk with the disk file, and actually wait for it to finish.
  • void sync (caddr_t address, size_t len) — sync a segment of memory that got mapped from a segment fetch.
  • void update (size_t offset=0, size_t len=0) — push a portion of the memory mapped from the file back to the file, no waiting around for completion.
  • void update (caddr_t address, size_t len) — update a mapped region back to disk, using address and length like a good lil spec.
  • void release (caddr_t address, size_t len) — release (aka unmap) a memory segment. 🕊️
  • caddr_t fetch (size_t offset=0) — fetch a pointer to an offset inside the memory-mapped portion of the disk file.
  • caddr_t fetch (off_t pos, size_t len) — fetch and map a portion of a disk file into a logical memory block.
  • bool lock (void) — lock the portion of the file that's currently mapped.
  • void unlock (void) — unlock a locked mapped portion of a file.
  • size_t pageAligned (size_t size) — compute map size so it lands on an aligned page boundry.

💫 Additional Inherited Members

(yeah, they exist. the page just vibes here.) 🌈

🦋 DESCRIPTION 🦋

Create and map a disk file into memory. periodt.

This portable class works under both Posix via mmap and under the win32 API. a mapped file can be referenced directly by its memory segment. you can map and unmap portions of a file on demand, and update changed memory pages that were mapped from files immediately through sync(). it's giving flexible 💅

Author

David Sugar dyfet@ostel.com

Map a named disk file into memory.

💜 Constructor & Destructor Documentation 💜

ost::MappedFile::MappedFile (const char * fname, Access mode)

Open a file for mapping. and lowkey the fun part: more than one segment of a file may be mapped into separate regions of memory. so go off, map as many lil slices as you want. 🍓

Parameters

  • fname — file name to access for mapping.
  • mode — access mode to map file.

ost::MappedFile::MappedFile (const char * fname, Access mode, size_t size)

Create if not exists, and map a file of specified size into memory. if it's not there, she's born. ✨

Parameters

  • fname — file name to access for mapping.
  • mode — access mode to map file.
  • size — of file to map.

ost::MappedFile::MappedFile (const char * fname, pos_t offset, size_t size, Access mode)

Map a portion or all of a specified file in the specified shared memory access mode. valid mapping modes include mappedRead, mappedWrite, and mappedReadWrite. pick your fighter. 🔥

Parameters

  • fname — pathname of file to map into memory.
  • offset — from start of file to begin mapping in bytes.
  • size — of mapped area in bytes.
  • mode — to map file.

virtual ost::MappedFile::~MappedFile () [virtual]

Release a mapped section of memory associated with a file. and ngl the mapped area gets updated back to disk on the way out. so she leaves everything tidy. 🫶

🌟 Member Function Documentation 🌟

caddr_t ost::MappedFile::fetch (off_t pos, size_t len)

Fetch and map a portion of a disk file to a logical memory block.

Returns

pointer to memory segment.

Parameters

  • pos — offset of file segment to map.
  • len — size of memory segment to map.

caddr_t ost::MappedFile::fetch (size_t offset = 0) [inline]

Fetch a pointer to an offset within the memory mapped portion of the disk file. fr this is really just for the convenience of matching up operations between Update and Fetch, since you could honestly have just accessed the base pointer where the file was mapped directly. but hey, it's handy. 🙈

Parameters

  • offset — from start of mapped memory.

bool ost::MappedFile::lock (void)

Lock the currently mapped portion of a file. 🔒

Returns

true if pages are locked.

size_t ost::MappedFile::pageAligned (size_t size)

Compute map size to aligned page boundry.

Parameters

  • size — request.

Returns

page aligned size.

void ost::MappedFile::release (caddr_t address, size_t len)

Release (unmap) a memory segment. let it goooo. 🕊️

Parameters

  • address — address of memory segment to release.
  • len — length of memory segment to release.

void ost::MappedFile::sync (caddr_t address, size_t len)

Synchronize a segment of memory mapped from a segment fetch.

Parameters

  • address — memory address to update.
  • len — size of segment.

void ost::MappedFile::sync (void)

Synchronize the contents of the mapped portion of memory with the disk file and wait for completion. this assures the memory mapped from the file is written back. no ghost writes, we wait. 💖

void ost::MappedFile::unlock (void)

Unlock a locked mapped portion of a file. 🔓

void ost::MappedFile::update (caddr_t address, size_t len)

Update a mapped region back to disk as specified by address and length.

Parameters

  • address — address of segment.
  • len — length of segment.

void ost::MappedFile::update (size_t offset = 0, size_t len = 0)

Map a portion of the memory mapped from the file back to the file and do not wait for completion. this is so useful when you're mapping a database file and updating a single record. one record, one lil push, no waiting. slay. 💅

Parameters

  • offset — offset into the mapped region of memory.
  • len — length of partial region (example, record length).

👑 AUTHOR 👑

Generated automatically by Doxygen for GNU CommonC++ from the source code.

okay that's the whole page bestie, go map something and hydrate 💧

GNU CommonC++ — Sun Dec 27 2020 — that's the version and the date, mwah, bye 💋🦋✨

📦 where this page comes from