db.h

About: hamsterdb is a database engine written in ANSI C. It supports a B+Tree index structure, uses

/*
 * get the memory allocator
 */
#define db_get_allocator(db)           (db_get_env(db)                        \
                                       ? env_get_allocator(db_get_env(db))    \
                                       : (db)->_allocator)

/*
 * set the memory allocator
 */
#define db_set_allocator(db, a)        ham_assert(db_get_env(db)==0, (""));   \
                                       (db)->_allocator=(a)

/*
 * get the device
 */
#define db_get_device(db)              (db_get_env(db)                        \
                                       ? env_get_device(db_get_env(db))       \
                                       : (db)->_device)

/*
 * set the device - not allowed in an environment
 */
#define db_set_device(db, d)           ham_assert(db_get_env(db)==0, (""));   \
                                       (db)->_device=(d)

/*
 * get the cache pointer
 */
#define db_get_cache(db)               (db_get_env(db)                        \
                                       ? env_get_cache(db_get_env(db))        \
                                       : (db)->_cache)

/*
 * set the cache pointer - not allowed in an environment
 */
#define db_set_cache(db, c)            ham_assert(db_get_env(db)==0, (""));   \
                                       (db)->_cache=c

/*
 * get the prefix comparison function
 */
#define db_get_prefix_compare_func(db) (db)->_prefixcompfoo

/*
 * set the prefix comparison function
 */
#define db_set_prefix_compare_func(db, f) (db)->_prefixcompfoo=f

/*
 * get the default comparison function
 */
#define db_get_compare_func(db)        (db)->_compfoo

/*
 * set the default comparison function
 */
#define db_set_compare_func(db, f)     (db)->_compfoo=f

/*
 * get the runtime-flags - if this database has an environment, the flags
 * are "mixed"
 */
#define db_get_rt_flags(db)            (db_get_env(db)                        \
                           ? env_get_rt_flags(db_get_env(db))|(db)->_rt_flags \
                           : (db)->_rt_flags)

/*
 * set the runtime-flags - NOT setting environment flags!
 */
#define db_set_rt_flags(db, f)         (db)->_rt_flags=(f)

/*
 * get the index of this database in the indexdata array
 */
#define db_get_indexdata_offset(db)    (db)->_indexdata_offset

/*
 * set the index of this database in the indexdata array
 */
#define db_set_indexdata_offset(db, o) (db)->_indexdata_offset=o

/*
 * get the environment pointer
 */
#define db_get_env(db)                 (db)->_env

/*
 * set the environment pointer
 */
#define db_set_env(db, env)            (db)->_env=env

/*
 * get the next database in a linked list of databases
 */
#define db_get_next(db)                (db)->_next

/*
 * set the pointer to the next database
 */
#define db_set_next(db, next)          (db)->_next=next

/*
 * get the size of the last allocated data blob
 */
#define db_get_record_allocsize(db)    (db)->_rec_allocsize

/*
 * set the size of the last allocated data blob
 */
#define db_set_record_allocsize(db, s) (db)->_rec_allocsize=s

/*
 * get the pointer to the last allocated data blob
 */
#define db_get_record_allocdata(db)    (db)->_rec_allocdata

/*
 * set the pointer to the last allocated data blob
 */
#define db_set_record_allocdata(db, p) (db)->_rec_allocdata=p

/*
 * get the size of the last allocated key blob
 */
#define db_get_key_allocsize(db)       (db)->_key_allocsize

/*
 * set the size of the last allocated key blob
 */
#define db_set_key_allocsize(db, s)    (db)->_key_allocsize=s

/*
 * get the pointer to the last allocated key blob
 */
#define db_get_key_allocdata(db)       (db)->_key_allocdata

/*
 * set the pointer to the last allocated key blob
 */
#define db_set_key_allocdata(db, p)    (db)->_key_allocdata=p
/*
 * get a pointer to the header data
 */
#define db_get_header(db)              ((db_header_t *)(page_get_payload(\
                                          db_get_header_page(db))))

/*
 * get the freelist object of the database
 * add 1 byte because the freelist starts AFTER _freelist_start!
 */
#define db_get_freelist(db)            (freelist_t *)(page_get_payload(  \
                                          db_get_header_page(db))+       \
                                          OFFSET_OF(db_header_t,         \
                                              _freelist_start)+1)

/*
 * get the dirty-flag
 */
#define db_is_dirty(db)                page_is_dirty(db_get_header_page(db))

/*
 * set the dirty-flag
 */
#define db_set_dirty(db, d)            page_set_dirty(db_get_header_page(db), d)

/**
 * uncouple all cursors from a page
 *
 * @remark this is called whenever the page is deleted or becoming invalid
 */
extern ham_status_t
db_uncouple_all_cursors(ham_page_t *page);

/**
 * compare two keys
 *
 * this function will call the prefix-compare function and the
 * default compare function whenever it's necessary.
 *
 * on error, the database error code (db_get_error()) is set; the caller
 * HAS to check for this error!
 *
 * the default key compare function - uses memcmp
 */
extern int
db_default_compare(const ham_u8_t *lhs, ham_size_t lhs_length,
                   const ham_u8_t *rhs, ham_size_t rhs_length);

/**
 * the default prefix compare function - uses memcmp
 */
extern int
db_default_prefix_compare(const ham_u8_t *lhs, ham_size_t lhs_length,
                   ham_size_t lhs_real_length,
                   const ham_u8_t *rhs, ham_size_t rhs_length,
                   ham_size_t rhs_real_length);

/**
 * load an extended key
 * returns the full data of the extended key in ext_key
 */
extern ham_status_t
db_get_extended_key(ham_db_t *db, ham_u8_t *key_data,
                    ham_size_t key_length, ham_u32_t key_flags,
                    ham_u8_t **ext_key);

/**
 * function which compares two keys
 *
 * calls the comparison function
 */
extern int
db_compare_keys(ham_db_t *db, ham_page_t *page,
                long lhs_idx, ham_u32_t lhs_flags,
                const ham_u8_t *lhs, ham_size_t lhs_length,
                long rhs_idx, ham_u32_t rhs_flags,
                const ham_u8_t *rhs, ham_size_t rhs_length);

/**
 * create a backend object according to the database flags
 */
extern ham_backend_t *
db_create_backend(ham_db_t *db, ham_u32_t flags);

/**
 * fetch a page
 */
extern ham_page_t *
db_fetch_page(ham_db_t *db, ham_offset_t address, ham_u32_t flags);
#define DB_ONLY_FROM_CACHE      2

/**
 * flush a page
 */
extern ham_status_t
db_flush_page(ham_db_t *db, ham_page_t *page, ham_u32_t flags);

/**
 * flush all pages, and clear the cache
 *
 * @param flags: set to DB_FLUSH_NODELETE if you do NOT want the cache to
 * be cleared
 */
extern ham_status_t
db_flush_all(ham_db_t *db, ham_u32_t flags);
#define DB_FLUSH_NODELETE       1

/**
 * allocate a new page
 *
 * !!! the page will be aligned at the current page size. any wasted
 * space (due to the alignment) is added to the freelist.
 * TODO nur wenn NO_ALIGN nicht gesetzt ist! (sollte das nicht eher der
 * default sein??)
 *
 * @remark flags can be of the following value:
 *  PAGE_IGNORE_FREELIST        ignores all freelist-operations
    PAGE_CLEAR_WITH_ZERO        memset the persistent page with 0
 */
extern ham_page_t *
db_alloc_page(ham_db_t *db, ham_u32_t type, ham_u32_t flags);
#define PAGE_IGNORE_FREELIST          2
#define PAGE_CLEAR_WITH_ZERO          4

/**
 * free a page
 *
 * @remark will mark the page as deleted; the page will be deleted
 * when the transaction is committed (or not deleted if the transaction
 * is aborted).
 *
 * @remark valid flag: DB_MOVE_TO_FREELIST; marks the page as 'deleted'
 * in the freelist. Ignored in in-memory databases.
 */
extern ham_status_t
db_free_page(ham_page_t *page, ham_u32_t flags);

#define DB_MOVE_TO_FREELIST         1

/**
 * write a page, then delete the page from memory
 *
 * @remark this function is used by the cache; it shouldn't be used
 * anywhere else.
 */
extern ham_status_t
db_write_page_and_delete(ham_page_t *page, ham_u32_t flags);

/**
 * an internal database flag - use mmap instead of read(2)
 */
#define DB_USE_MMAP                  0x00000100

#ifdef __cplusplus
} // extern "C" {
#endif

#endif /* HAM_DB_H__ */