120 lines
4.2 KiB
Plaintext
120 lines
4.2 KiB
Plaintext
m4_comment([$Id: memp_fget.so,v 10.48 2006/09/13 14:30:54 mjc Exp $])
|
|
|
|
define(M4PAGELOCAL,
|
|
[memp_fget, DB_MPOOL_CREATE, DB_MPOOL_DIRTY, DB_MPOOL_EDIT,
|
|
DB_MPOOL_LAST, DB_MPOOL_NEW,
|
|
DB_PAGE_NOTFOUND, DB_LOCK_DEADLOCK])
|
|
include(m4/m4.seealso)
|
|
|
|
m4_pf_header(m4_ref(memp_fget),
|
|
ifelse(M4API, C_API, [dnl
|
|
int
|
|
DB_MPOOLFILE-__GT__get(DB_MPOOLFILE *mpf,
|
|
db_pgno_t *pgnoaddr, DB_TXN * txnid, u_int32_t flags, void **pagep);
|
|
])
|
|
ifelse(M4API, CXX_API, [dnl
|
|
int
|
|
DbMpoolFile::get(db_pgno_t *pgnoaddr,
|
|
DbTxn *txnid, u_int32_t flags, void **pagep);
|
|
]))
|
|
|
|
m4_p([dnl
|
|
The m4_refT(memp_fget) returns pages from the cache.])
|
|
|
|
m4_p([dnl
|
|
All pages returned by m4_ref(memp_fget) will be retained (that is,
|
|
m4_italic(pinned)), in the pool until a subsequent call to
|
|
m4_ref(memp_fput).])
|
|
|
|
m4_p([The returned page is m4_bold(size_t) type aligned.])
|
|
|
|
m4_p([dnl
|
|
Fully or partially created pages have all their bytes set to a nul byte,
|
|
unless the m4_refT(memp_set_clear_len) was called to specify other
|
|
behavior before the file was opened.])
|
|
|
|
m4_idefz(DB_PAGE_NOTFOUND)
|
|
m4_return(memp_fget, except, DB_PAGE_NOTFOUND,
|
|
[if the requested page does not exist and m4_ref(DB_MPOOL_CREATE) was
|
|
not set], prev)
|
|
|
|
m4_parambegin
|
|
m4_param(flags, [dnl
|
|
m4_sf_or_may
|
|
|
|
m4_tagbegin
|
|
m4_tag(m4_idef(DB_MPOOL_CREATE), [dnl
|
|
If the specified page does not exist, create it. In this case, the
|
|
m4_linkpage(memp_register, pgin, pgin) method, if specified, is
|
|
called.])
|
|
|
|
m4_tag(m4_idef(DB_MPOOL_DIRTY), [dnl
|
|
The page will be modified and must be written to the source file before
|
|
being evicted from the pool. For files open with the
|
|
m4_ref(DB_MULTIVERSION) flag set, a new copy of the page will be made
|
|
if this is the first time the specified transaction is modifying it.])
|
|
|
|
m4_tag(m4_idef(DB_MPOOL_EDIT), [dnl
|
|
The page will be modified and must be written to the source file before
|
|
being evicted from the pool. No copy of the page will be made, regardless
|
|
of the m4_ref(DB_MULTIVERSION) setting. This flag is only intended for
|
|
use in situations where a transaction handle is not available, such as during
|
|
aborts or recovery.])
|
|
|
|
m4_tag(m4_idef(DB_MPOOL_LAST), [dnl
|
|
Return the last page of the source file, and copy its page number into
|
|
the memory location to which m4_arg(pgnoaddr) refers.])
|
|
|
|
m4_tag(m4_idef(DB_MPOOL_NEW), [dnl
|
|
Create a new page in the file, and copy its page number into the memory
|
|
location to which m4_arg(pgnoaddr) refers. In this case, the
|
|
m4_linkpage(memp_register, pgin, pgin) method, if specified, is
|
|
m4_bold(not) called.])
|
|
m4_tagend
|
|
|
|
m4_p([dnl
|
|
The m4_ref(DB_MPOOL_CREATE), m4_ref(DB_MPOOL_LAST), and
|
|
m4_ref(DB_MPOOL_NEW) flags are mutually exclusive.])])
|
|
|
|
m4_param_co(pagep, returned page, REF)
|
|
|
|
m4_param(pgnoaddr, [dnl
|
|
If the m4_arg(flags) parameter is set to m4_ref(DB_MPOOL_LAST) or
|
|
m4_ref(DB_MPOOL_NEW), the page number of the created page is copied
|
|
into the memory location to which the m4_arg(pgnoaddr) parameter
|
|
refers. Otherwise, the m4_arg(pgnoaddr) parameter is the page to
|
|
create or retrieve.
|
|
m4_p([m4_bold([dnl
|
|
Page numbers begin at 0; that is, the first page in the file is page
|
|
number 0, not page number 1.])])])
|
|
|
|
m4_param(txnid, [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. A transaction is
|
|
required if the file is open for multiversion concurrency control by
|
|
passing m4_ref(DB_MULTIVERSION) to m4_ref(memp_fopen) and the
|
|
m4_ref(DB_MPOOL_DIRTY), m4_ref(DB_MPOOL_CREATE) or
|
|
m4_ref(DB_MPOOL_NEW) flags were specified. Otherwise it is ignored.])
|
|
m4_paramend
|
|
|
|
m4_err(memp_fget,
|
|
EACCES,
|
|
[The m4_ref(DB_MPOOL_DIRTY) or m4_ref(DB_MPOOL_EDIT) flag was set and
|
|
the source file was not opened for writing.],
|
|
EAGAIN,
|
|
[The page reference count has overflowed. (This should never happen
|
|
unless there is a bug in the application.)],
|
|
einval,
|
|
[the m4_ref(DB_MPOOL_NEW) flag was set, and the source file was not
|
|
opened for writing;
|
|
more than one of m4_ref(DB_MPOOL_CREATE), m4_ref(DB_MPOOL_LAST), and
|
|
m4_ref(DB_MPOOL_NEW) was set.],
|
|
m4_ref(DB_LOCK_DEADLOCK),
|
|
[For transactions configured with m4_ref(DB_TXN_SNAPSHOT), the page has
|
|
been modified since the transaction began.],
|
|
memory,
|
|
[cache is full, and no more pages will fit in the pool])
|
|
|
|
m4_seealso(DbMpool)
|
|
m4_page_footer
|