#include <db_cxx.h>

int
DbMpoolFile::get(db_pgno_t *pgnoaddr, u_int32_t flags, void **pagep);

Description: DbMpoolFile::get

The DbMpoolFile::get method returns pages from the cache.

All pages returned by DbMpoolFile::get will be retained (that is, pinned), in the pool until a subsequent call to DbMpoolFile::put.

The returned page is size_t type aligned.

Fully or partially created pages have all their bytes set to a nul byte, unless the DbMpoolFile::set_clear_len method was called to specify other behavior before the file was opened.

The DbMpoolFile::get method will either return DB_PAGE_NOTFOUND or throw an exception that encapsulates DB_PAGE_NOTFOUND if the requested page does not exist and DB_MPOOL_CREATE was not set. Unless otherwise specified, the DbMpoolFile::get method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Parameters

flags

The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

DB_MPOOL_CREATE

If the specified page does not exist, create it. In this case, the pgin method, if specified, is called.

DB_MPOOL_LAST

Return the last page of the source file, and copy its page number into the memory location to which pgnoaddr refers.

DB_MPOOL_NEW

Create a new page in the file, and copy its page number into the memory location to which pgnoaddr refers. In this case, the pgin method, if specified, is not called.

The DB_MPOOL_CREATE, DB_MPOOL_LAST, and DB_MPOOL_NEW flags are mutually exclusive.

pagep

The pagep parameter references memory into which a pointer to the returned page is copied.

pgnoaddr

If the flags parameter is set to DB_MPOOL_LAST or DB_MPOOL_NEW, the page number of the created page is copied into the memory location to which the pgnoaddr parameter refers. Otherwise, the pgnoaddr parameter is the page to create or retrieve.

Page numbers begin at 0; that is, the first page in the file is page number 0, not page number 1.

Errors

The DbMpoolFile::get method may fail and throw DbException, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EAGAIN

The page reference count has overflowed. (This should never happen unless there is a bug in the application.)

EINVAL

If the DB_MPOOL_NEW flag was set, and the source file was not opened for writing; more than one of DB_MPOOL_CREATE, DB_MPOOL_LAST, and DB_MPOOL_NEW was set; or if an invalid flag value or parameter was specified.

If the cache is full, and no more pages will fit in the pool, the DbMpoolFile::get method will fail and either return ENOMEM or throw a DbMemoryException.

Class

See Also