file.h

GNU Common C++ is a very portable and highly optimized class framework for writing C++ applications

	 * Get current file capacity.
	 *
	 * @return total file size.
	 */
	off_t getCapacity(void);

	/**
	 * 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.
	 */
	virtual Error restart(void);

	/**
	 * Return current error id.
	 *
	 * @return last error identifier set.
	 */
	inline Error getErrorNumber(void)
		{return errid;};

	/**
	 * Return current error string.
	 *
	 * @return last error string set.
	 */
	inline char *getErrorString(void)
		{return errstr;};

	bool operator!(void);
};

/**
 * This class defines a database I/O file service that can be shared
 * by multiple threads.  All threads access a global copy of the database
 * object, and mutex locks can be used to preserve transaction
 * integrety.  pread/pwrite calls can be used for optimized I/O when
 * supported.
 * 
 * ThreadFile is meant for use by a threaded database server where multiple
 * threads may each perform semi-independent operations on a given database
 * table stored on disk.  A special "fcb" structure is used to hold file
 * "state", and pread/pwrite is used whenever possible for optimized I/O.  On
 * systems that do not offer pwread/pwrite, a Mutex lock is used to protect
 * concurrent lseek and read/write operations.  ThreadFile managed databases
 * are assumed to be used only by the local server and through a single file
 * descriptor.
 *
 * @author David Sugar <[e-mail]>
 * @short This class defines a database I/O file service that can be shared by multiple threads.
 */
class __EXPORT ThreadFile : public RandomFile
{
private:
	ThreadKey state;
	fcb_t *first;
	fcb_t *getFCB(void);
	Error open(const char *path);

public:
	/**
	 * Open or create a new database file.  You should also use
	 * Initial.
	 *
	 * @param path pathname of database to open.
	 */
	ThreadFile(const char *path);

	/**
	 * Close and finish a database file.
	 */
	virtual ~ThreadFile();

	/**
	 * Restart an existing database; close and re-open.
	 *
	 * @return errSuccess if successful.
	 */
	Error restart(void);

	/**
	 * Fetch a portion of the file into physical memory.  This can use
	 * state information to fetch the current record multiple times.
	 *
	 * @return errSuccess on success.
	 * @param address  address to use, or NULL if same as last I/O.
	 * @param length   length to use, or 0 if same as last I/O.
	 * @param position file position to use -1 if same as last I/O.
	 */
	Error fetch(caddr_t address = NULL, ccxx_size_t length = 0, off_t position = -1);

	/**
	 * Update a portion of a file from physical memory.  This can use
	 * state information to commit the last read record.
	 *
	 * @return errSuccess on success.
	 * @param address  address to use, or NULL if same as last I/O.
	 * @param length   length to use, or 0 if same as last I/O.
	 * @param position file position to use or -1 if same as last I/O.
	 */
	Error update(caddr_t address = NULL, ccxx_size_t length = 0, off_t position = -1);

	/**
	 * Add new data to the end of the file.
	 * @param address address to use, or NULL if same as last I/O.
	 * @param length  length to use, or 0 if same as last I/O.
	 */
	Error append(caddr_t address = NULL, ccxx_size_t length = 0);

	/**
	 * Fetch the current file position marker for this thread.
	 *
	 * @return file position offset.
	 */
	off_t getPosition(void);

	bool operator++(void);
	bool operator--(void);
};

/**
 * This class defines a database I/O file service that can be shared
 * by multiple processes.  Each thread should access a dup of the database
 * object, and mutex locks can be used to preserve transaction
 * integrety if multiple threads are used.
 *
 * SharedFile is used when a database may be shared between multiple
 * processes.  SharedFile automatically applies low level byte-range "file
 * locks", and provides an interface to fetch and release byte-range locked
 * portions of a file.
 *
 * @author David Sugar <[e-mail]>
 * @short This class defines a database I/O file service that can be shared by multiple processes.
 */
class __EXPORT SharedFile : public RandomFile
{
private:
	fcb_t fcb;
	Error open(const char *path);

public:
	/**
	 * Open or create a new database file.  You should also use
	 * Initial.
	 *
	 * @param path pathname of database to open.
	 */
	SharedFile(const char *path);

	/**
	 * Create a shared file as a duplicate of an existing shared
	 * file.
	 *
	 * @param file original file.
	 */
	SharedFile(const SharedFile &file);

	/**
	 * Close and finish a database file.
	 */
	virtual ~SharedFile();

	/**
	 * Restart an existing database; close and re-open.
	 *
	 * @return errSuccess if successful.
	 */
	Error restart(void)
		{return open(pathname);};

	/**
	 * Lock and Fetch a portion of the file into physical memory.
         * This can use state information to fetch the current record
         * multiple times.
	 *
	 * @return errSuccess on success.
	 * @param address  address to use, or NULL if same as last I/O.
	 * @param length   length to use, or 0 if same as last I/O.
	 * @param position file position to use -1 if same as last I/O.
	 */
	Error fetch(caddr_t address = NULL, ccxx_size_t length = 0, off_t position = -1);

	/**
	 * Update a portion of a file from physical memory.  This can use
	 * state information to commit the last read record.  The current
	 * lock is also cleared.
	 *
	 * @return errSuccess on success.
	 * @param address  address to use, or NULL if same as last I/O.
	 * @param length   length to use, or 0 if same as last I/O.
	 * @param position file position to use or -1 if same as last I/O.
	 */
	Error update(caddr_t address = NULL, ccxx_size_t length = 0, off_t position = -1);

	/**
	 * Clear a lock held from a previous fetch operation without
	 * updating.
	 *
	 * @return errSuccess on success.
	 * @param length length to use, or 0 if same as last I/O.
	 * @param pos    file position to use or -1 if same as last I/O.
	 */
	Error clear(ccxx_size_t length = 0, off_t pos = -1);

	/**
	 * Add new data to the end of the file.  Locks file during append.
	 *
	 * @param address address to use, or NULL if same as last I/O.
	 * @param length  length to use, or 0 if same as last I/O.
	 */
	Error append(caddr_t address = NULL, ccxx_size_t length = 0);

	/**
	 * Fetch the current file position marker for this thread.
	 *
	 * @return file position offset.
	 */
	off_t getPosition(void);

	bool operator++(void);
	bool operator--(void);
};

/**
 * 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 <[e-mail]>
 * @short Map a named disk file into memory.
 */
class __EXPORT MappedFile : public RandomFile
{
private:
	fcb_t fcb;
	int prot;
#ifdef	WIN32
	HANDLE map;
	char mapname[64];
#endif

public:
	/**
	 * Open a file for mapping.  More than one segment of a file
	 * may be mapped into seperate regions of memory.
	 *
	 * @param fname file name to access for mapping.
	 * @param mode  access mode to map file.
	 */
	MappedFile(const char *fname, Access mode);

	/**
	 * Create if not exists, and map a file of specified size
	 * into memory.
	 *
	 * @param fname file name to access for mapping.
	 * @param mode access mode to map file.
	 * @param size of file to map.
	 */
	MappedFile(const char *fname, Access mode, size_t size);

	/**
	 * Map a portion or all of a specified file in the specified
	 * shared memory access mode.  Valid mapping modes include
	 * mappedRead, mappedWrite, and mappedReadWrite.
	 *
	 * @param fname pathname of file to map into memory.
	 * @param offset from start of file to begin mapping in bytes.
	 * @param size of mapped area in bytes.
	 * @param mode to map file.
	 */
	MappedFile(const char *fname, pos_t offset, size_t size, Access mode);

	/**
	 * Release a mapped section of memory associated with a file.  The
	 * mapped area is updated back to disk.
	 */
	virtual ~MappedFile();

	// FIXME: not use library function in header ??
	/**
	 * 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 sync(void);

	/**
	 * Synchronize a segment of memory mapped from a segment fetch.
	 *
	 * @param address memory address to update.
	 * @param len size of segment.
	 */
	void sync(caddr_t address, size_t len);

	/**
	 * 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.
	 *
	 * @param offset offset into the mapped region of memory.
	 * @param len length of partial region (example, record length).
	 */
	void update(size_t offset = 0, size_t len = 0);

	/**
	 * Update a mapped region back to disk as specified by address
	 * and length.
	 *
	 * @param address address of segment.
	 * @param len length of segment.
	 */
	void update(caddr_t address, size_t len);

	/**
	 * Release (unmap) a memory segment.
	 *
	 * @param address address of memory segment to release.
	 * @param len length of memory segment to release.
	 */
	void release(caddr_t address, size_t len);

	/**
	 * 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.
	 *
	 * @param offset from start of mapped memory.
	 */
	inline caddr_t fetch(size_t offset = 0)
		{return ((char *)(fcb.address)) + offset;};

	/**
	 * Fetch and map a portion of a disk file to a logical memory
	 * block.
	 *
	 * @return pointer to memory segment.
	 * @param pos offset of file segment to map.
	 * @param len size of memory segment to map.
	 */
	caddr_t fetch(off_t pos, size_t len);

	/**
	 * Lock the currently mapped portion of a file.
	 *
	 * @return true if pages are locked.
	 */
	bool lock(void);

	/**
	 * Unlock a locked mapped portion of a file.
	 */
	void unlock(void);

	/**
	 * Compute map size to aligned page boundry.
	 *
	 * @param size request.
	 * @return page aligned size.
	 */
	size_t pageAligned(size_t size);
};


/**
 * The DSO dynamic loader class is used to load object files.  On
 * elf based systems this is typically done with dlopen.  A dummy
 * stub class is generated for non-dl capable systems.
 *
 * @author David Sugar <[e-mail]>
 * @short Dynamic class file loader.
 */
class __EXPORT DSO
{
private:
	const char *err;
#ifdef	HAVE_MODULES
	static Mutex mutex;
	static DSO *first;
	static DSO *last;
	DSO *next, *prev;
	const char *id;
#if	defined(HAVE_MACH_DYLD)
        NSModule oModule;
#elif   defined(HAVE_SHL_LOAD)
        shl_t image;
#elif	defined(WIN32)
	HINSTANCE hImage;
#else
	void *image;
#endif
	void loader(const char *filename, bool resolve);
#endif

public:
	/**
	 * Construct and load a DSO object file.
	 *
	 * @param filename pathname of object file to load.
	 */ 
#ifdef	HAVE_MODULES
	DSO(const char *filename)
		{loader(filename, true);};

	DSO(const char *filename, bool resolve)
		{loader(filename, resolve);};
#else
	DSO(const char *filename)
		{throw this;};
	DSO(const char *filename, bool resolve)
		{throw this;};
#endif

	/**
	 * Retrieve error indicator associated with DSO failure.  This
	 * is often used in catch handlers.
	 */
	inline const char *getError(void)
		{return err;};

	/**
	 * Detach a DSO object from running memory.
	 */
#ifdef	HAVE_MODULES
	virtual ~DSO();
#endif

	/**
	 * Lookup a symbol in the loaded file.
	 */
#ifdef	HAVE_MODULES
	void* operator[](const char *sym);
#else
	void *operator[](const char *)
		{return NULL;};
#endif

#ifdef	HAVE_MODULES
	static void dynunload(void);
#else
	static void dynunload(void)
		{return;};
#endif

	/**
	 * Find a specific DSO object by filename.
	 *
	 * @param name of DSO object file (partial).
	 */
	static DSO *getObject(const char *name);

	/**
	 * See if DSO object is valid.
	 *
	 * @return true if valid.
	 */
	bool isValid(void);

	/**
	 * Install debug handler...
	 */
	static void setDebug(void);
};

/** @relates RandomFile */
bool __EXPORT isDir(const char *path);
/** @relates RandomFile */
bool __EXPORT isFile(const char *path);
#ifndef WIN32
/** @relates RandomFile */
bool __EXPORT isDevice(const char *path);
#else
/** @relates RandomFile */
inline bool isDevice(const char *path)
{ return false; }
#endif
/** @relates RandomFile */
bool __EXPORT canAccess(const char *path);
/** @relates RandomFile */
bool __EXPORT canModify(const char *path);
/** @relates RandomFile */
time_t __EXPORT lastModified(const char *path);
/** @relates RandomFile */
time_t __EXPORT lastAccessed(const char *path);

#ifdef	COMMON_STD_EXCEPTION

class DirException : public IOException
{
public:
	DirException(const String &str) : IOException(str) {};
};

class __EXPORT DSOException : public IOException
{
public:
	DSOException(const String &str) : IOException(str) {};
};

class __EXPORT FileException : public IOException
{
public:
	FileException(const String &str) : IOException(str) {};
};

#endif

#ifdef	CCXX_NAMESPACES
}
#endif

#endif

/** EMACS **
 * Local variables:
 * mode: c++
 * c-basic-offset: 8
 * End:
 */