m4_comment([$Id: env_set_cachesize.so,v 10.51 2007/07/06 00:22:52 mjc Exp $])

ifdef([M4INTERFACE],, [define(M4INTERFACE, dbenv_set_cachesize)])
define(M4GETINTERFACE, ifelse(M4INTERFACE,
    dbenv_set_cachesize, dbenv_get_cachesize, dbh_get_cachesize))

define(M4PAGELOCAL, [M4INTERFACE, M4GETINTERFACE, dbenv_get_cachesize_ncache])
include(m4/m4.seealso)

ifelse(M4INTERFACE, dbenv_set_cachesize, [dnl
m4_pf_header(m4_ref(dbenv_set_cachesize),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__set_cachesize(DB_ENV *dbenv,
    u_int32_t gbytes, u_int32_t bytes, int ncache);
m4_blank
int
DB_ENV-__GT__get_cachesize(DB_ENV *dbenv,
    u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::set_cachesize(u_int32_t gbytes, u_int32_t bytes, int ncache);
m4_blank
int
DbEnv::get_cachesize(u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
]))],[dnl
m4_pf_header(m4_ref(dbh_set_cachesize),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_cachesize(DB *db,
    u_int32_t gbytes, u_int32_t bytes, int ncache);
m4_blank
int
DB-__GT__get_cachesize(DB *db,
    u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
])dnl
ifelse(M4API, CXX_API, [dnl
int
Db::set_cachesize(u_int32_t gbytes, u_int32_t bytes, int ncache);
int
Db::get_cachesize(u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
]))])

m4_p([dnl
Set the size of the shared memory buffer pool -- that is, the cache.
The cache should be the size of the normal working data set of the
application, with some small amount of additional memory for unusual
situations.  (Note: the working set is not the same as the number of
pages accessed simultaneously, and is usually much larger.)])

m4_p([dnl
The default cache size is 256KB, and may not be specified as less than
20KB.  Any cache size less than 500MB is automatically increased by 25%
to account for buffer pool overhead; cache sizes larger than 500MB are
used as specified.  The maximum size of a single cache is 4GB on 32-bit
systems and 10TB on 64-bit systems.  (All sizes are in powers-of-two,
that is, 256KB is 2^18 not 256,000.) For information on tuning the m4_db
cache size, see m4_link(M4RELDIR/ref/am_conf/cachesize, [Selecting a
cache size]).])

m4_p([dnl
It is possible to specify caches to m4_db large enough they cannot be
allocated contiguously on some architectures.  For example, some
releases of Solaris limit the amount of memory that may be allocated
contiguously by a process.  If m4_arg(ncache) is 0 or 1, the cache will
be allocated contiguously in memory.  If it is greater than 1, the cache
will be split across m4_arg(ncache) separate regions, where the
m4_bold(region size) is equal to the initial cache size divided by
m4_arg(ncache).])

ifelse(M4INTERFACE, dbenv_set_cachesize, [dnl
m4_p([dnl
The memory pool may be resized by calling m4_ref(dbenv_set_cachesize)
after the environment is open.  The supplied size will be rounded to
the nearest multiple of the region size and may not be larger than the
maximum size configured with m4_ref(dbenv_set_cache_max).  The
m4_arg(ncache) parameter is ignored when resizing the cache.])])

ifelse(M4INTERFACE, dbenv_set_cachesize, [dnl
m4_env_config(dbenv_set_cachesize, [initial cache size], set_cachesize,
[the initial cache size specified in three parts: the gigabytes of
cache, the additional bytes of cache, and the number of caches, also
separated by whitespace characters.  For example, "set_cachesize 2
524288000 3" would create a 2.5GB logical cache, split between three
physical caches])

m4_scope_env(dbenv_set_cachesize)
m4_when_any(dbenv_set_cachesize)
m4_return(dbenv_set_cachesize, std)
],[dnl
m4_p([dnl
Because databases opened within m4_db environments use the cache
specified to the environment, it is an error to attempt to set a cache
in a database created within an environment.])

m4_when_dbopen(dbh_set_cachesize)

m4_return(dbh_set_cachesize, std)])

m4_parambegin
m4_param(bytes, [dnl
The size of the cache is set to m4_arg(gbytes) gigabytes plus m4_arg(bytes).])
m4_param(gbytes, [dnl
The size of the cache is set to m4_arg(gbytes) gigabytes plus m4_arg(bytes).])
m4_param(ncache, [dnl
The m4_arg(ncache) parameter is the number of caches to create.])
m4_paramend

m4_err(M4INTERFACE, einval,
[the specified cache size was impossibly small;
ifelse(M4INTERFACE, dbh_set_cachesize, [the method was called after
m4_ref(dbh_open) was called])])

m4_pf_description(m4_ref(M4GETINTERFACE))
m4_p([dnl
The m4_refT(M4GETINTERFACE) returns the current size and composition of the
cache.])

m4_when_any(M4GETINTERFACE)

m4_return(M4GETINTERFACE, std)

m4_parambegin
m4_param_co(bytesp, additional bytes of memory in the cache)
m4_param_co(gbytesp, gigabytes of memory in the cache)
m4_param_co(ncachep, number of caches)
m4_paramend

ifelse(M4INTERFACE, dbenv_set_cachesize, [m4_seealso(DbEnv)], [m4_seealso(Db)])
m4_page_footer