229 lines
9.7 KiB
Plaintext
229 lines
9.7 KiB
Plaintext
m4_comment([$Id])
|
|
|
|
define(M4PAGELOCAL,
|
|
[dbenv_set_flags, dbenv_get_flags, DB_CDB_ALLDB, DB_DIRECT_DB,
|
|
DB_DSYNC_DB, DB_MULTIVERSION, DB_NOLOCKING,
|
|
DB_NOMMAP, DB_NOPANIC, DB_OVERWRITE, DB_PANIC_ENVIRONMENT,
|
|
DB_REGION_INIT, DB_TIME_NOTGRANTED, DB_TXN_NOSYNC, DB_TXN_NOWAIT,
|
|
DB_TXN_SNAPSHOT, DB_TXN_WRITE_NOSYNC, DB_YIELDCPU])
|
|
include(m4/m4.seealso)
|
|
|
|
m4_pf_header(m4_ref(dbenv_set_flags),
|
|
ifelse(M4API, C_API, [dnl
|
|
int
|
|
DB_ENV-__GT__set_flags(DB_ENV *dbenv, u_int32_t flags, int onoff);
|
|
m4_blank
|
|
int
|
|
DB_ENV-__GT__get_flags(DB_ENV *dbenv, u_int32_t *flagsp);
|
|
])
|
|
ifelse(M4API, CXX_API, [dnl
|
|
int
|
|
DbEnv::set_flags(u_int32_t flags, int onoff);
|
|
m4_blank
|
|
int
|
|
DbEnv::get_flags(u_int32_t *flagsp)
|
|
]))
|
|
|
|
m4_p([dnl
|
|
Configure a database environment.])
|
|
|
|
m4_env_config(dbenv_set_flags, flag values, set_flags, [dnl
|
|
the method flag parameter as a string; for example, "set_flags
|
|
DB_TXN_NOSYNC"])
|
|
|
|
m4_return(dbenv_set_flags, std)
|
|
|
|
m4_parambegin
|
|
m4_param(flags, [dnl
|
|
m4_sf_or_must
|
|
|
|
m4_tagbegin
|
|
|
|
m4_tag(m4_idef(DB_AUTO_COMMIT), [dnl
|
|
If set, m4_ref(Db) handle operations for which no explicit transaction
|
|
handle was specified, and which modify databases in the database
|
|
environment, will be automatically enclosed within a transaction.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_AUTO_COMMIT, config)
|
|
m4_env_flags_any(DB_AUTO_COMMIT)])
|
|
|
|
m4_idefz([configure @locking for m4_cam])
|
|
m4_tag(m4_idef(DB_CDB_ALLDB), [dnl
|
|
If set, m4_cam applications will perform locking on an environment-wide
|
|
basis rather than on a per-database basis.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_CDB_ALLDB, config)
|
|
m4_env_flags_open(DB_CDB_ALLDB, before)])
|
|
|
|
m4_idefz([turn off system @buffering for database files])
|
|
m4_tag(m4_idef(DB_DIRECT_DB), [dnl
|
|
Turn off system buffering of m4_db database files to avoid double caching.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_DIRECT_DB, config)
|
|
m4_env_flags_any(DB_DIRECT_DB)])
|
|
|
|
m4_idefz([turn off system @buffering for database files])
|
|
m4_tag(m4_idef(DB_DSYNC_DB), [dnl
|
|
Configure m4_db to flush database writes to the backing disk before
|
|
returning from the write system call, rather than flushing database
|
|
writes explicitly in a separate system call, as necessary. This is only
|
|
available on some systems (for example, systems supporting the
|
|
m4_posix1_name standard O_DSYNC flag, or systems supporting the Windows
|
|
FILE_FLAG_WRITE_THROUGH flag). This flag may result in inaccurate file
|
|
modification times and other file-level information for m4_db database
|
|
files. This flag will almost certainly result in a performance decrease
|
|
on most systems. This flag is only applicable to certain filesysystem
|
|
(for example, the Veritas VxFS filesystem), where the filesystem's
|
|
support for trickling writes back to stable storage behaves badly (or
|
|
more likely, has been misconfigured).
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_DSYNC_DB, config)
|
|
m4_env_flags_any(DB_DSYNC_DB)])
|
|
|
|
m4_tag(m4_idef(DB_MULTIVERSION), [dnl
|
|
If set, all databases in the environment will be opened as if
|
|
m4_ref(DB_MULTIVERSION) is passed to m4_ref(dbh_open). This flag will
|
|
be ignored for queue databases for which m4_ref(DB_MULTIVERSION) is not
|
|
supported.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_MULTIVERSION, config)
|
|
m4_env_flags_any(DB_MULTIVERSION)])
|
|
|
|
m4_idefz([ignore @locking])
|
|
m4_tag(m4_idef(DB_NOLOCKING), [dnl
|
|
If set, m4_db will grant all requested mutual exclusion mutexes and
|
|
database locks without regard for their actual availability. This
|
|
functionality should never be used for purposes other than debugging.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_NOLOCKING)
|
|
m4_env_flags_any(DB_NOLOCKING)])
|
|
|
|
m4_idefz([turn off database file @memory mapping])
|
|
m4_tag(m4_idef(DB_NOMMAP), [dnl
|
|
If set, m4_db will copy read-only database files into the local cache
|
|
instead of potentially mapping them into process memory (see the
|
|
description of the m4_refT(dbenv_set_mp_mmapsize) for further
|
|
information).
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_NOMMAP, config)
|
|
m4_env_flags_any(DB_NOMMAP)])
|
|
|
|
m4_idefz([ignore database environment @panic])
|
|
m4_tag(m4_idef(DB_NOPANIC), [dnl
|
|
If set, m4_db will ignore any panic state in the database environment.
|
|
(Database environments in a panic state normally refuse all attempts to
|
|
call m4_db functions, returning m4_ref(DB_RUNRECOVERY).) This
|
|
functionality should never be used for purposes other than debugging.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_NOPANIC)
|
|
m4_env_flags_any(DB_NOPANIC)])
|
|
|
|
m4_tag(m4_idef(DB_OVERWRITE), [dnl
|
|
Overwrite files stored in encrypted formats before deleting them. m4_db
|
|
overwrites files using alternating 0xff, 0x00 and 0xff byte patterns.
|
|
For file overwriting to be effective, the underlying file must be stored
|
|
on a fixed-block filesystem. Systems with journaling or logging filesystems
|
|
will require operating system support and probably modification of the
|
|
m4_db sources.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_OVERWRITE)
|
|
m4_env_flags_any(DB_OVERWRITE)])
|
|
|
|
m4_idefz([turn off access to a database @environment])
|
|
m4_tag(m4_idef(DB_PANIC_ENVIRONMENT), [dnl
|
|
If set, m4_db will set the panic state for the database environment.
|
|
(Database environments in a panic state normally refuse all attempts to
|
|
call m4_db functions, returning m4_ref(DB_RUNRECOVERY).) This flag may
|
|
not be specified using the environment's m4_ref(DB_CONFIG) file.
|
|
m4_scope_env_flags(dbenv_set_flags, DB_PANIC_ENVIRONMENT)
|
|
m4_env_flags_open(DB_PANIC_ENVIRONMENT, after)])
|
|
|
|
m4_idefz([fault database @environment in during open])
|
|
m4_tag(m4_idef(DB_REGION_INIT), [dnl
|
|
In some applications, the expense of page-faulting the underlying shared
|
|
memory regions can affect performance. (For example, if the page-fault
|
|
occurs while holding a lock, other lock requests can convoy, and overall
|
|
throughput may decrease.) If set, m4_db will page-fault shared regions
|
|
into memory when initially creating or joining a m4_db environment. In
|
|
addition, m4_db will write the shared regions when creating an
|
|
environment, forcing the underlying virtual memory and filesystems to
|
|
instantiate both the necessary memory and the necessary disk space.
|
|
This can also avoid out-of-disk space failures later on.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_REGION_INIT, config)
|
|
m4_env_flags_any(DB_REGION_INIT)])
|
|
|
|
m4_tag(m4_idef(DB_TIME_NOTGRANTED), [dnl
|
|
If set, database calls timing out based on lock or transaction timeout
|
|
values will
|
|
ifelse(M4EXCEPT, return_only, [dnl
|
|
return m4_ref(DB_LOCK_NOTGRANTED) instead of m4_ref(DB_LOCK_DEADLOCK).],[dnl
|
|
throw a m4_ref(DbLockNotGrantedException) exception instead of
|
|
m4_ref(DbDeadlockException).])
|
|
This allows applications to distinguish between operations which have
|
|
deadlocked and operations which have exceeded their time limits.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_TIME_NOTGRANTED, config)
|
|
m4_env_flags_any(DB_TIME_NOTGRANTED)])
|
|
|
|
m4_idefz([turn off synchronous @transaction commit])
|
|
m4_tag(m4_idef(DB_TXN_NOSYNC), [dnl
|
|
If set, m4_db will not write or synchronously flush the log on transaction
|
|
commit.
|
|
This means that transactions exhibit the ACI (atomicity, consistency,
|
|
and isolation) properties, but not D (durability); that is, database
|
|
integrity will be maintained, but if the application or system fails,
|
|
it is possible some number of the most recently committed transactions
|
|
may be undone during recovery. The number of transactions at risk is
|
|
governed by how many log updates can fit into the log buffer, how often
|
|
the operating system flushes dirty buffers to disk, and how often the
|
|
log is checkpointed.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_NOSYNC,
|
|
config) m4_env_flags_any(DB_TXN_NOSYNC)])
|
|
|
|
m4_tag(m4_idef(DB_TXN_NOWAIT), [dnl
|
|
If set and a lock is unavailable for any m4_db operation performed in
|
|
the context of a transaction, cause the operation to
|
|
ifelse(M4EXCEPT, return_only, [dnl
|
|
return m4_ref(DB_LOCK_DEADLOCK) (or m4_ref(DB_LOCK_NOTGRANTED) if
|
|
configured using the m4_ref(DB_TIME_NOTGRANTED) flag).],[dnl
|
|
either return m4_ref(DB_LOCK_DEADLOCK) or throw a
|
|
m4_ref(DbDeadlockException) exception (or return
|
|
m4_ref(DB_LOCK_NOTGRANTED) or throw a m4_ref(DbLockNotGrantedException)
|
|
exception if configured using the m4_ref(DB_TIME_NOTGRANTED) flag).])
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_NOWAIT, config)
|
|
m4_env_flags_any(DB_TXN_NOWAIT)])
|
|
|
|
m4_tag(m4_idef(DB_TXN_SNAPSHOT), [dnl
|
|
If set, all transactions in the environment will be started as if
|
|
m4_ref(DB_TXN_SNAPSHOT) were passed to m4_ref(txn_begin), and all
|
|
non-transactional cursors will be opened as if m4_ref(DB_TXN_SNAPSHOT)
|
|
were passed to m4_ref(dbh_cursor).
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_SNAPSHOT, config)
|
|
m4_env_flags_any(DB_TXN_SNAPSHOT)])
|
|
|
|
m4_idefz([turn off synchronous @transaction commit])
|
|
m4_tag(m4_idef(DB_TXN_WRITE_NOSYNC), [dnl
|
|
If set, m4_db will write, but will not synchronously flush, the log on
|
|
transaction commit.
|
|
This means that transactions exhibit the ACI (atomicity, consistency,
|
|
and isolation) properties, but not D (durability); that is, database
|
|
integrity will be maintained, but if the system fails, it is possible
|
|
some number of the most recently committed transactions may be undone
|
|
during recovery. The number of transactions at risk is governed by how
|
|
often the system flushes dirty buffers to disk and how often the log is
|
|
checkpointed.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_WRITE_NOSYNC, config)
|
|
m4_env_flags_any(DB_TXN_WRITE_NOSYNC)])
|
|
|
|
m4_idefz([configure for @stress testing])
|
|
m4_tag(m4_idef(DB_YIELDCPU), [dnl
|
|
If set, m4_db will yield the processor immediately after each page or
|
|
mutex acquisition. This functionality should never be used for purposes
|
|
other than stress testing.
|
|
m4_scope_dbenv_flags(dbenv_set_flags, DB_YIELDCPU, config)
|
|
m4_env_flags_any(DB_YIELDCPU)])
|
|
|
|
m4_tagend])
|
|
|
|
m4_param(onoff, [dnl
|
|
If the m4_arg(onoff) parameter is zero, the specified flags are cleared;
|
|
otherwise they are set.])
|
|
m4_paramend
|
|
|
|
m4_err(dbenv_set_flags, einval)
|
|
|
|
m4_pf_getter(dbenv_get_flags, configuration flags,, flagsp)
|
|
|
|
m4_seealso(DbEnv)
|
|
m4_page_footer
|