m4_comment([$Id: db_compact.so,v 1.8 2008/04/30 15:25:34 mbrey Exp $])

define(M4PAGELOCAL, dbh_compact)
include(m4/m4.seealso)

m4_pf_header(m4_ref(dbh_compact),
ifelse(M4API, C_API, [dnl
int
DB-__GT__compact(DB *db, DB_TXN *txnid,
    DBT *start, DBT *stop, DB_COMPACT *c_data, u_int32_t flags, DBT *end);
])
ifelse(M4API, CXX_API, [dnl
int
Db::compact(DbTxn *txnid,
    Dbt *start, Dbt *stop, DB_COMPACT *c_data, u_int32_t flags, Dbt *end);
]))

m4_p([dnl
The m4_refT(dbh_compact) compacts Btree and Recno access method
databases, and optionally returns unused Btree, Hash or Recno database
pages to the underlying filesystem.])

m4_return(dbh_compact, std)

m4_parambegin

m4_param(txnid, [dnl
If the operation is part of an application-specified transaction, the
m4_arg(txnid) parameter is a transaction handle returned from
m4_ref(txn_begin); otherwise NULL.  If no transaction handle is
specified, but the operation occurs in a transactional database, the
operation will be implicitly transaction protected using multiple
transactions.  These transactions will be periodically committed to
avoid locking large sections of the tree.  Any deadlocks encountered
cause the compaction operation to retried from the point of the last
transaction commit.])

m4_param(start, [dnl
If non-NULL, the m4_arg(start) parameter is the starting point for
compaction in a Btree or Recno database.  Compaction will start at the
smallest key greater than or equal to the specified key.  If NULL,
compaction will start at the beginning of the database.])

m4_param(stop, [dnl
If non-NULL, the m4_arg(stop) parameter is the stopping point for
compaction in a Btree or Recno database.  Compaction will stop at the
page with the smallest key greater than the specified key.  If NULL,
compaction will stop at the end of the database.])

m4_param(c_data, [m4_p([dnl
If non-NULL, the m4_arg(c_data) parameter contains additional compaction
configuration parameters, and returns compaction operation statistics,
in a structure of type DB_COMPACT.])
m4_p([dnl
The following input configuration fields are available from the
DB_COMPACT structure:])
m4_tagbegin
m4_field(int, compact_fillpercent, [dnl
If non-zero, the goal for filling pages, specified as a percentage
between 1 and 100.  Any page in a Btree or Recno databases not at or
above this percentage full will be considered for compaction.  The
default behavior is to consider every page for compaction, regardless
of its page fill percentage.])
m4_field(int, compact_pages, [dnl
If non-zero, the call will return after that number of pages have been
freed.])
m4_field(db_timeout_t, compact_timeout, [dnl
If non-zero, and no m4_arg(txnid) parameter was specified, the lock
timeout set for implicit transactions, in microseconds.])
m4_tagend
m4_p([dnl
The following output statistics fields are available from the
DB_COMPACT structure:])
m4_tagbegin
m4_field(u_int32_t, compact_deadlock, [dnl
An output statistics parameter: if no m4_arg(txnid) parameter was
specified, the number of deadlocks which occurred.])
m4_field(u_int32_t, compact_pages_examine, [dnl
An output statistics parameter: the number of database pages reviewed
during the compaction phase.])
m4_field(u_int32_t, compact_pages_free, [dnl
An output statistics parameter: the number of database pages freed during
the compaction phase.])
m4_field(u_int32_t, compact_levels, [dnl
An output statistics parameter: the number of levels removed from the
Btree or Recno database during the compaction phase.])
m4_field(u_int32_t, compact_pages_truncated, [dnl
An output statistics parameter: the number of database pages returned
to the filesystem.])
m4_tagend])

m4_param(flags, [dnl
m4_sf_zmust
m4_tagbegin
m4_tag(m4_idef(DB_FREELIST_ONLY), [dnl
Do no page compaction, only returning pages to the filesystem that are
already free and at the end of the file.  This flag must be set if the
database is a Hash access method database.])
m4_tag(m4_idef(DB_FREE_SPACE), [dnl
Return pages to the filesystem when possible.
If this flag is not specified, pages emptied as a result of compaction
will be placed on the free list for re-use, but never returned to the
filesystem.
m4_p([dnl
Note that only pages at the end of a file can be returned to the
filesystem.  Because of the one-pass nature of the compaction algorithm,
any not emptied page near the end of the file inhibits returning pages to
the file system.  A repeated call to the m4_refT(dbh_compact) with a low
m4_arg(compact_fillpercent) may be used to return pages in this case.])])
m4_tagend])

m4_param(end, [dnl
If non-NULL, the m4_arg(end) parameter will be filled in with the
database key marking the end of the compaction operation in a Btree or
Recno database.  This is generally the first key of the page where the
operation stopped.])

m4_paramend

m4_err(dbh_compact, deadlock, rephandle, replockout, readonly, einval,,)

m4_seealso(Db)
m4_page_footer