m4_comment([$Id: ram.so,v 10.10 2006/09/19 15:42:31 bostic Exp $])m4_ref_title(Programmer Notes,    Memory-only or Flash configurations,    Flash memory configurations, program/namespace, program/cache)m4_p([dnlm4_db supports a variety of memory-based configurations for systemswhere filesystem space is either limited in availability or entirelyreplaced by some combination of memory and Flash.  In addition, m4_dbcan be configured to minimize writes to the filesystem when thefilesystem is backed by Flash memory.])m4_p([dnlThere are three parts of the m4_db database environment normally writtento the filesystem: the database environment region files, the databasefiles and the database environment log files.  Each of these items canbe configured to live in memory rather than in the filesystem:])m4_tagbeginm4_tag([The database environment region files:], [dnlEach of the m4_db subsystems in a database environment is described byone or more regions, or chunks of memory. The regions contain all of theper-process and per-thread shared information (including mutexes), thatcomprise a m4_db environment.  By default, these regions are backed bythe filesystem.  In situations where filesystem backed regions aren'toptimal, applications can create memory-only database environments intwo different types of memory: either in the application's heap memoryor in system shared memory.m4_p([dnlTo create the database environment in heap memory, specify them4_ref(DB_PRIVATE) flag to the m4_refT(dbenv_open).  Note that databaseenvironments created in heap memory are only accessible to the threadsof a single process, however.])m4_p([dnlTo create the database environment in system shared memory, specify them4_ref(DB_SYSTEM_MEM) flag to the m4_refT(dbenv_open).  Databaseenvironments created in system memory are accessible to multipleprocesses, but note that database environments created in system sharedmemory do create a small (roughly 8 byte) file in the filesystem, readby the processes to identify which system shared memory segments touse.])m4_p([dnlFor more information, see m4_link(M4RELDIR/ref/env/region, [Sharedmemory regions]).])])m4_tag([The database files:], [dnlBy default, databases are periodically flushed from the m4_db memorycache to backing physical files in the filesystem.  To keep databasesfrom being written to backing physical files, pass them4_ref(DB_MPOOL_NOFILE) flag to the m4_refT(memp_set_flags).  This flagimplies the application's databases must fit entirely in the m4_dbcache, of course.  To avoid a database file growing to consume theentire cache, applications can limit the size of individual databasesin the cache by calling the m4_refT(memp_set_maxsize).])m4_tag([The database environment log files:], [dnlIf a database environment is not intended to be transactionallyrecoverable after application or system failure (that is, if it will notexhibit the transactional attribute of "durability"), applicationsshould not configure the database environment for logging ortransactions, in which case no log files will be created.  If thedatabase environment is intended to be durable, log files must eitherbe written to stable storage and recovered after application or systemfailure, or they must be replicated to other systems.m4_p([dnlIn applications running on systems without any form of stable storage,durability must be accomplished through replication.  In this case,database environments should be configured to maintain database logs inmemory, rather than in the filesystem, by specifying them4_ref(DB_LOG_INMEMORY) flag to the m4_refT(dbenv_set_flags).])])m4_tagendm4_p([dnlIn systems where the filesystem is backed by Flash memory, the numberof times the Flash memory is written may be a concern.  Each of thethree parts of the m4_db database environment normally written to thefilesystem can be configured to minimize the number of times thefilesystem is written:])m4_tagbeginm4_tag([The database environment region files:], [dnlOn a Flash-based filesystem, the database environment should be placedin heap or system memory, as described previously.])m4_tag([The database files:], [dnlThe m4_db library maintains a cache of database pages.  The databasepages are only written to backing physical files when the applicationcheckpoints the database environment with the m4_refT(txn_checkpoint),when database handles are closed with the m4_refT(dbh_close), or whenthe application explicitly flushes the cache with the m4_ref(dbh_sync)or m4_refT(memp_sync)s.m4_p([dnlTo avoid unnecessary writes of Flash memory due to checkpoints,applications should decrease the frequency of their checkpoints.  Thisis especially important in applications which repeatedly modify aspecific database page, as repeatedly writing a database page to thebacking physical file will repeatedly update the same blocks of thefilesystem.])m4_p([dnlTo avoid unnecessary writes of the filesystem due to closing a databasehandle, applications should specify the m4_ref(DB_NOSYNC) flag to them4_refT(dbh_close).])m4_p([dnlTo avoid unnecessary writes of the filesystem due to flushing the cache,applications should not explicitly flush the cache under normalconditions -- flushing the cache is rarely if ever needed in anormally-running application.])])m4_tag([The database environment log files:], [dnlThe m4_db log files do not repeatedly overwrite the same blocks of thefilesystem as the m4_db log files are not implemented as a circularbuffer and log files are not re-used.  For this reason, the m4_db logfiles should not cause any difficulties for Flash memory configurations.m4_p([dnlHowever, as m4_db does not write log records in filesystem block sizedpieces, it is probable that sequential transaction commits (each ofwhich flush the log file to the backing filesystem), will write a blockof Flash memory twice, as the last log record from the first commit willwrite the same block of Flash memory as the first log record from thesecond commit.  Applications not requiring absolute durability shouldspecify the m4_ref(DB_TXN_WRITE_NOSYNC) or m4_ref(DB_TXN_NOSYNC) flagsto the m4_refT(dbenv_set_flags) to avoid this overwrite of a block ofFlash memory.])])m4_tagendm4_page_footer