m4_comment([$Id: region.so,v 10.33 2005/06/11 12:32:49 bostic Exp $])

m4_ref_title(Environment, Shared memory regions,, env/naming, env/security)

m4_p([dnl
Each of the m4_db subsystems within an environment is described by one
or more regions, or chunks of memory.  The regions contain all of the
per-process and per-thread shared information (including mutexes), that
comprise a m4_db environment.  These regions are created in one of three
types of memory, depending on the flags specified to the
m4_refT(dbenv_open):])

m4_nlistbegin
m4_nlist([dnl
If the m4_ref(DB_PRIVATE) flag is specified to the m4_refT(dbenv_open),
regions are created in per-process heap memory; that is, memory returned
by m4_manref(malloc, 3).
m4_p([dnl
This flag should not be specified if more than a single process is
accessing the environment because it is likely to cause database
corruption and unpredictable behavior.  For example, if both a server
application and m4_db utilities (for example, m4_ref(db_archive),
m4_ref(db_checkpoint) or m4_ref(db_stat)) are expected to access the
environment, the m4_ref(DB_PRIVATE) flag should not be specified.])])

m4_nlist([dnl
If the m4_ref(DB_SYSTEM_MEM) flag is specified to m4_ref(dbenv_open),
shared regions are created in system memory rather than files.  This is
an alternative mechanism for sharing the m4_db environment among
multiple processes and multiple threads within processes.])

m4_p([dnl
The system memory used by m4_db is potentially useful past the lifetime
of any particular process.  Therefore, additional cleanup may be
necessary after an application fails because there may be no way for
m4_db to ensure that system resources backing the shared memory regions
are returned to the system.])

m4_p([dnl
The system memory that is used is architecture-dependent.  For example,
on systems supporting X/Open-style shared memory interfaces, such as
UNIX systems, the m4_manref(shmget, 2) and related System V IPC
interfaces are used. Additionally, VxWorks systems use system memory.
In these cases, an initial segment ID must be specified by the
application to ensure that applications do not overwrite each other's
database environments, so that the number of segments created does not
grow without bounds.  See the m4_refT(dbenv_set_shm_key) for more
information.])

m4_p([dnl
On Windows platforms, the use of the m4_ref(DB_SYSTEM_MEM) flag is
problematic because the operating system uses reference counting to
clean up shared objects in the paging file automatically.  In addition,
the default access permissions for shared objects are different from
files, which may cause problems when an environment is accessed by
multiple processes running as different users.  See
m4_link(M4RELDIR/ref/build_win/notes, [Windows Notes]) for more
information.])

m4_nlist([dnl
If no memory-related flags are specified to m4_ref(dbenv_open), memory
backed by the filesystem is used to store the regions.  On UNIX systems,
the m4_db library will use the POSIX mmap interface. If mmap is not available,
the UNIX shmget interfaces may be used instead, if they are available.])

m4_nlistend

m4_idefz(__db.001)
m4_p([dnl
Any files created in the filesystem to back the regions are created in
the environment home directory specified to the m4_ref(dbenv_open) call.
These files are named [__db.###] (for example, __db.001, __db.002 and
so on).  When region files are backed by the filesystem, one file per
region is created.  When region files are backed by system memory, a
single file will still be created because there must be a well-known
name in the filesystem so that multiple processes can locate the system
shared memory that is being used by the environment.])

m4_p([dnl
Statistics about the shared memory regions in the environment can be
displayed using the m4_option(e) option to the m4_ref(db_stat) utility.])

m4_page_footer