MappedFile Class Reference

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

#include <file.h>

Inheritance diagram for MappedFile:

Collaboration diagram for MappedFile:

Public Types
enum	Error {   errSuccess = 0, errNotOpened, errMapFailed, errInitFailed,   errOpenDenied, errOpenFailed, errOpenInUse, errReadInterrupted,   errReadIncomplete, errReadFailure, errWriteInterrupted, errWriteIncomplete,   errWriteFailure, errLockFailure, errExtended }
typedef enum Error	Error
enum	Access { accessReadOnly = O_RDONLY, accessWriteOnly = O_WRONLY, accessReadWrite = O_RDWR }
typedef enum Access	Access
enum	Open {   openReadOnly = O_RDONLY, openWriteOnly = O_WRONLY, openReadWrite = O_RDWR, openAppend = O_WRONLY | O_APPEND,   openSync = O_RDWR, openTruncate = O_RDWR | O_TRUNC }
typedef enum Open	Open
enum	Attr { attrInvalid = 0, attrPrivate = 0400 | 0200, attrGroup = attrPrivate | 0040 | 0020, attrPublic = attrGroup | 0004 | 0002 }
typedef enum Attr	Attr
enum	Mapping { mappedRead = accessReadOnly, mappedWrite = accessWriteOnly, mappedReadWrite = accessReadWrite }
typedef enum Mapping	Mapping
enum	Complete { completionImmediate, completionDelayed, completionDeferred }
typedef enum Complete	Complete

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...
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)

Static Public Member Functions
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
typedef struct File::_fcb	fcb_t

Protected Member Functions
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...
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
static void	setDebug (bool mode)
	Enable or disable deadlock debugging. More...

Protected Attributes
int	fd
Access	access
char *	pathname
struct {
unsigned   count: 16
bool   thrown: 1
bool   initial: 1
bool   immediate: 1
bool   temp: 1
}	flags

Private Attributes
fcb_t	fcb
int	prot

Related Functions
(Note that these are not member functions.)
bool __EXPORT	isDir (const char *path)
bool __EXPORT	isFile (const char *path)
bool __EXPORT	isDevice (const char *path)
bool __EXPORT	canAccess (const char *path)
bool __EXPORT	canModify (const char *path)
time_t __EXPORT	lastModified (const char *path)
time_t __EXPORT	lastAccessed (const char *path)

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.

Definition at line 747 of file file.h.

Member Typedef Documentation

typedef enum Access File::Access

inherited

Definition at line 150 of file file.h.

typedef enum Attr File::Attr

inherited

Definition at line 213 of file file.h.

typedef enum Complete File::Complete

inherited

Definition at line 239 of file file.h.

typedef enum Error File::Error

inherited

Definition at line 137 of file file.h.

typedef struct File::_fcb File::fcb_t

protectedinherited

typedef enum Mapping File::Mapping

inherited

Definition at line 240 of file file.h.

typedef enum Open File::Open

inherited

Definition at line 183 of file file.h.

Member Enumeration Documentation

enum File::Access

inherited

Enumerator
accessReadOnly
accessWriteOnly
accessReadWrite

Definition at line 139 of file file.h.

enum File::Attr

inherited

Enumerator
attrInvalid
attrPrivate
attrGroup
attrPublic

Definition at line 199 of file file.h.

enum File::Complete

inherited

Enumerator
completionImmediate
completionDelayed
completionDeferred

Definition at line 233 of file file.h.

enum File::Error

inherited

Enumerator
errSuccess
errNotOpened
errMapFailed
errInitFailed
errOpenDenied
errOpenFailed
errOpenInUse
errReadInterrupted
errReadIncomplete
errReadFailure
errWriteInterrupted
errWriteIncomplete
errWriteFailure
errLockFailure
errExtended

Definition at line 120 of file file.h.

enum File::Mapping

inherited

Enumerator
mappedRead
mappedWrite
mappedReadWrite

Definition at line 228 of file file.h.

enum File::Open

inherited

Enumerator
openReadOnly
openWriteOnly
openReadWrite
openAppend
openSync
openTruncate

Definition at line 171 of file file.h.

Constructor & Destructor Documentation

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

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

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

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

Parameters

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

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

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 MappedFile::~MappedFile ( )

virtual

Release a mapped section of memory associated with a file.

The mapped area is updated back to disk.

Member Function Documentation

void Mutex::enter ( void  )

inlineinherited

Future abi will use enter/leave/test members.

Definition at line 263 of file thread.h.

void Mutex::enterMutex ( void  )

inherited

Entering a Mutex locks the mutex for the current thread.

This also can be done using the ENTER_CRITICAL macro or by using the ++ operator on a mutex.

See Also

leaveMutex

Error RandomFile::error ( Error  errid, char *  errstr = NULL  )

protectedinherited

Post an error event.

Returns

error code.

Parameters

errid	error code.
errstr	error message string.

Error RandomFile::error ( char *  err )

inlineprotectedinherited

Post an extended string error message.

Returns

errExtended.

Parameters

err	error string.

Definition at line 447 of file file.h.

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

offset

from start of mapped memory.

Definition at line 846 of file file.h.

char* 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.

void RandomFile::final ( void  )

protectedinherited

Close the file.

off_t RandomFile::getCapacity ( void  )

inherited

Get current file capacity.

Returns

total file size.

static char* File::getDirname ( const char *  path, char *  buffer, size_t  size = 256  )

staticinherited

Error RandomFile::getErrorNumber ( void  )

inlineinherited

Return current error id.

Returns

last error identifier set.

Definition at line 532 of file file.h.

char* RandomFile::getErrorString ( void  )

inlineinherited

Return current error string.

Returns

last error string set.

Definition at line 540 of file file.h.

static const char* File::getExtension ( const char *  path )

staticinherited

static const char* File::getFilename ( const char *  path )

staticinherited

static char* File::getFilename ( const char *  path, char *  buffer, size_t  size = 64  )

staticinherited

static char* File::getRealpath ( const char *  path, char *  buffer, size_t  size = 256  )

staticinherited

bool RandomFile::initial ( void  )

inherited

This method should be called right after a RandomFile derived object has been created.

This method will invoke initialize if the object is newly created, and set file access permissions appropriately.

Returns

true if file had to be initialized.

virtual Attr RandomFile::initialize ( void  )

protectedvirtualinherited

This method is used to initialize a newly created file as indicated by the "initial" flag.

This method also returns the file access permissions that should be associated with the file. This method should never be called directly, but is instead used to impliment the "Initial" method. Typically one would use this to build an empty database shell when a previously empty database file is created.

Returns

access, or attrInvalid if should be removed.

void Mutex::leave ( void  )

inlineinherited

Future abi will use enter/leave/test members.

Definition at line 269 of file thread.h.

void Mutex::leaveMutex ( void  )

inherited

Leaving a mutex frees that mutex for use by another thread.

If the mutex has been entered (invoked) multiple times (recursivily) by the same thread, then it will need to be exited the same number of instances before it is free for re-use. This operation can also be done using the LEAVE_CRITICAL macro or by the – operator on a mutex.

See Also

enterMutex

bool MappedFile::lock

(

void

)

Lock the currently mapped portion of a file.

Returns

true if pages are locked.

void Mutex::nameMutex ( const char *  name )

inlineinherited

Enable setting of mutex name for deadlock debug.

Parameters

name	for mutex.

Definition at line 248 of file thread.h.

bool RandomFile::operator! ( void  )

inherited

size_t MappedFile::pageAligned

(

size_t

size

)

Compute map size to aligned page boundry.

Parameters

size

request.

Returns

page aligned size.

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

Release (unmap) a memory segment.

Parameters

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

virtual Error RandomFile::restart ( void  )

virtualinherited

This method is commonly used to close and re-open an existing database.

This may be used when the database has been unlinked and an external process provides a new one to use.

Reimplemented in SharedFile, and ThreadFile.

Error RandomFile::setCompletion ( Complete  mode )

protectedinherited

Used to set file completion modes.

Returns

errSuccess if okay.

Parameters

mode	completion mode.

Todo:

implement in win32

static void Mutex::setDebug ( bool  mode )

inlinestaticinherited

Enable or disable deadlock debugging.

Parameters

mode	debug mode.

Definition at line 240 of file thread.h.

void RandomFile::setError ( bool  enable )

inlineprotectedinherited

Used to enable or disable throwing of exceptions on errors.

Parameters

enable

true if errors will be thrown.

Definition at line 456 of file file.h.

void RandomFile::setTemporary ( bool  enable )

inlineprotectedinherited

Used to set the temporary attribute for the file.

Temporary files are automatically deleted when closed.

Parameters

enable

true for marking as temporary.

Definition at line 476 of file file.h.

void 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.

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

Synchronize a segment of memory mapped from a segment fetch.

Parameters

address	memory address to update.
len	size of segment.

bool Mutex::test ( void  )

inlineinherited

Future abi will use enter/leave/test members.

Returns

true if entered.

Definition at line 277 of file thread.h.

bool Mutex::tryEnterMutex ( void  )

inherited

Tries to lock the mutex for the current thread.

Behaves like enterMutex , except that it doesn't block the calling thread if the mutex is already locked by another thread.

Returns

true if locking the mutex was succesful otherwise false

See Also

enterMutex

leaveMutex

void MappedFile::unlock

(

void

)

Unlock a locked mapped portion of a file.

void 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

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

void MappedFile::update	(	char *	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.

Friends And Related Function Documentation

bool __EXPORT canAccess ( const char *  path )

related

bool __EXPORT canModify ( const char *  path )

related

bool __EXPORT isDevice ( const char *  path )

related

bool __EXPORT isDir ( const char *  path )

related

bool __EXPORT isFile ( const char *  path )

related

time_t __EXPORT lastAccessed ( const char *  path )

related

time_t __EXPORT lastModified ( const char *  path )

related

Field Documentation

Access RandomFile::access

protectedinherited

Definition at line 406 of file file.h.

unsigned RandomFile::count

inherited

Definition at line 413 of file file.h.

fcb_t MappedFile::fcb

private

Definition at line 750 of file file.h.

int RandomFile::fd

protectedinherited

Definition at line 404 of file file.h.

struct { ... } RandomFile::flags

bool RandomFile::immediate

inherited

Definition at line 417 of file file.h.

bool RandomFile::initial

inherited

Definition at line 415 of file file.h.

char* RandomFile::pathname

protectedinherited

Definition at line 410 of file file.h.

int MappedFile::prot

private

Definition at line 751 of file file.h.

bool RandomFile::temp

inherited

Definition at line 419 of file file.h.

bool RandomFile::thrown

inherited

Definition at line 414 of file file.h.

---

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

• file.h