GNU CommonC++
Public Member Functions | List of all members
ost::MappedFile Class Reference

Create and map a disk file into memory. More...

#include <file.h>

Inheritance diagram for ost::MappedFile:
ost::RandomFile ost::Mutex ost::File

Public Member Functions

 MappedFile (const char *fname, Access mode)
 Open a file for mapping. More...
 
 MappedFile (const char *fname, Access mode, size_t size)
 Create if not exists, and map a file of specified size into memory. More...
 
 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. More...
 
virtual ~MappedFile ()
 Release a mapped section of memory associated with a file. More...
 
void sync (void)
 Synchronize the contents of the mapped portion of memory with the disk file and wait for completion. More...
 
void sync (char *address, size_t len)
 Synchronize a segment of memory mapped from a segment fetch. More...
 
void 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. More...
 
void update (char *address, size_t len)
 Update a mapped region back to disk as specified by address and length. More...
 
void release (char *address, size_t len)
 Release (unmap) a memory segment. More...
 
char * fetch (size_t offset=0)
 Fetch a pointer to an offset within the memory mapped portion of the disk file. More...
 
char * fetch (off_t pos, size_t len)
 Fetch and map a portion of a disk file to a logical memory block. More...
 
bool lock (void)
 Lock the currently mapped portion of a file. More...
 
void unlock (void)
 Unlock a locked mapped portion of a file. More...
 
size_t pageAligned (size_t size)
 Compute map size to aligned page boundry. More...
 
- Public Member Functions inherited from ost::RandomFile
virtual ~RandomFile ()
 Destroy a random access file or it's derived class. More...
 
bool initial (void)
 This method should be called right after a RandomFile derived object has been created. More...
 
off_t getCapacity (void)
 Get current file capacity. More...
 
virtual Error restart (void)
 This method is commonly used to close and re-open an existing database. More...
 
Error getErrorNumber (void)
 Return current error id. More...
 
char * getErrorString (void)
 Return current error string. More...
 
bool operator! (void)
 

Additional Inherited Members

- Public Types inherited from ost::File
enum  Error {
  errSuccess = 0, errNotOpened, errMapFailed, errInitFailed,
  errOpenDenied, errOpenFailed, errOpenInUse, errReadInterrupted,
  errReadIncomplete, errReadFailure, errWriteInterrupted, errWriteIncomplete,
  errWriteFailure, errLockFailure, errExtended
}
 
enum  Access { accessReadOnly = O_RDONLY, accessWriteOnly = O_WRONLY, accessReadWrite = O_RDWR }
 
enum  Open {
  openReadOnly = O_RDONLY, openWriteOnly = O_WRONLY, openReadWrite = O_RDWR, openAppend = O_WRONLY | O_APPEND,
  openSync = O_RDWR, openTruncate = O_RDWR | O_TRUNC
}
 
enum  Attr { attrInvalid = 0, attrPrivate = 0400 | 0200, attrGroup = attrPrivate | 0040 | 0020, attrPublic = attrGroup | 0004 | 0002 }
 
enum  Mapping { mappedRead = accessReadOnly, mappedWrite = accessWriteOnly, mappedReadWrite = accessReadWrite }
 
enum  Complete { completionImmediate, completionDelayed, completionDeferred }
 
typedef enum Error Error
 
typedef enum Access Access
 
typedef enum Open Open
 
typedef enum Attr Attr
 
typedef enum Complete Complete
 
typedef enum Mapping Mapping
 
- Static Public Member Functions inherited from ost::File
static const char * getExtension (const char *path)
 
static const char * getFilename (const char *path)
 
static char * getFilename (const char *path, char *buffer, size_t size=64)
 
static char * getDirname (const char *path, char *buffer, size_t size=256)
 
static char * getRealpath (const char *path, char *buffer, size_t size=256)
 
- Protected Types inherited from ost::File
typedef struct ost::File::_fcb fcb_t
 
enum  Error {
  errSuccess = 0, errNotOpened, errMapFailed, errInitFailed,
  errOpenDenied, errOpenFailed, errOpenInUse, errReadInterrupted,
  errReadIncomplete, errReadFailure, errWriteInterrupted, errWriteIncomplete,
  errWriteFailure, errLockFailure, errExtended
}
 
enum  Access { accessReadOnly = O_RDONLY, accessWriteOnly = O_WRONLY, accessReadWrite = O_RDWR }
 
enum  Open {
  openReadOnly = O_RDONLY, openWriteOnly = O_WRONLY, openReadWrite = O_RDWR, openAppend = O_WRONLY | O_APPEND,
  openSync = O_RDWR, openTruncate = O_RDWR | O_TRUNC
}
 
enum  Attr { attrInvalid = 0, attrPrivate = 0400 | 0200, attrGroup = attrPrivate | 0040 | 0020, attrPublic = attrGroup | 0004 | 0002 }
 
enum  Mapping { mappedRead = accessReadOnly, mappedWrite = accessWriteOnly, mappedReadWrite = accessReadWrite }
 
enum  Complete { completionImmediate, completionDelayed, completionDeferred }
 
typedef enum Error Error
 
typedef enum Access Access
 
typedef enum Open Open
 
typedef enum Attr Attr
 
typedef enum Complete Complete
 
typedef enum Mapping Mapping
 
- Protected Member Functions inherited from ost::RandomFile
 RandomFile (const char *name=NULL)
 Create an unopened random access file. More...
 
 RandomFile (const RandomFile &rf)
 Default copy constructor. More...
 
Error error (Error errid, char *errstr=NULL)
 Post an error event. More...
 
Error error (char *err)
 Post an extended string error message. More...
 
void setError (bool enable)
 Used to enable or disable throwing of exceptions on errors. More...
 
Error setCompletion (Complete mode)
 Used to set file completion modes. More...
 
void setTemporary (bool enable)
 Used to set the temporary attribute for the file. More...
 
virtual Attr initialize (void)
 This method is used to initialize a newly created file as indicated by the "initial" flag. More...
 
void final (void)
 Close the file. More...
 
- Protected Member Functions inherited from ost::Mutex
 Mutex (const char *name=NULL)
 The mutex is always initialized as a recursive entity. More...
 
virtual ~Mutex ()
 Destroying the mutex removes any system resources associated with it. More...
 
void nameMutex (const char *name)
 Enable setting of mutex name for deadlock debug. More...
 
void enterMutex (void)
 Entering a Mutex locks the mutex for the current thread. More...
 
void enter (void)
 Future abi will use enter/leave/test members. More...
 
void leave (void)
 Future abi will use enter/leave/test members. More...
 
bool test (void)
 Future abi will use enter/leave/test members. More...
 
bool tryEnterMutex (void)
 Tries to lock the mutex for the current thread. More...
 
void leaveMutex (void)
 Leaving a mutex frees that mutex for use by another thread. More...
 
- Static Protected Member Functions inherited from ost::Mutex
static void setDebug (bool mode)
 Enable or disable deadlock debugging. More...
 
- Static Protected Member Functions inherited from ost::File
static const char * getExtension (const char *path)
 
static const char * getFilename (const char *path)
 
static char * getFilename (const char *path, char *buffer, size_t size=64)
 
static char * getDirname (const char *path, char *buffer, size_t size=256)
 
static char * getRealpath (const char *path, char *buffer, size_t size=256)
 
- Protected Attributes inherited from ost::RandomFile
int fd
 
Access access
 
char * pathname
 
struct {
   unsigned   count: 16
 
   bool   thrown: 1
 
   bool   initial: 1
 
   bool   immediate: 1
 
   bool   temp: 1
 
flags
 

Detailed Description

Create and map a disk file into memory.

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

Author
David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m Map a named disk file into memory.

Constructor & Destructor Documentation

◆ MappedFile() [1/3]

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

Open a file for mapping.

More than one segment of a file may be mapped into seperate regions of memory.

Parameters
fnamefile name to access for mapping.
modeaccess mode to map file.

◆ MappedFile() [2/3]

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

Create if not exists, and map a file of specified size into memory.

Parameters
fnamefile name to access for mapping.
modeaccess mode to map file.
sizeof file to map.

◆ MappedFile() [3/3]

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.

Parameters
fnamepathname of file to map into memory.
offsetfrom start of file to begin mapping in bytes.
sizeof mapped area in bytes.
modeto map file.

◆ ~MappedFile()

virtual ost::MappedFile::~MappedFile ( )
virtual

Release a mapped section of memory associated with a file.

The mapped area is updated back to disk.

Member Function Documentation

◆ fetch() [1/2]

char* ost::MappedFile::fetch ( size_t  offset = 0)
inline

Fetch a pointer to an offset within the memory mapped portion of the disk file.

This really is used for convience of matching operations between Update and Fetch, as one could simply have accessed the base pointer where the file was mapped directly.

Parameters
offsetfrom start of mapped memory.

References ost::File::_fcb::address.

◆ fetch() [2/2]

char* 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
posoffset of file segment to map.
lensize of memory segment to map.

◆ lock()

bool ost::MappedFile::lock ( void  )

Lock the currently mapped portion of a file.

Returns
true if pages are locked.

◆ pageAligned()

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

Compute map size to aligned page boundry.

Parameters
sizerequest.
Returns
page aligned size.

◆ release()

void ost::MappedFile::release ( char *  address,
size_t  len 
)

Release (unmap) a memory segment.

Parameters
addressaddress of memory segment to release.
lenlength of memory segment to release.

◆ sync() [1/2]

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.

◆ sync() [2/2]

void ost::MappedFile::sync ( char *  address,
size_t  len 
)

Synchronize a segment of memory mapped from a segment fetch.

Parameters
addressmemory address to update.
lensize of segment.

◆ unlock()

void ost::MappedFile::unlock ( void  )

Unlock a locked mapped portion of a file.

◆ update() [1/2]

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 useful when mapping a database file and updating a single record.

Parameters
offsetoffset into the mapped region of memory.
lenlength of partial region (example, record length).

◆ update() [2/2]

void ost::MappedFile::update ( char *  address,
size_t  len 
)

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

Parameters
addressaddress of segment.
lenlength of segment.

The documentation for this class was generated from the following file: