packages feed

rocksdb-haskell-jprupp-2.8.0: cbits/rocksdb_haskell.h

/*
 * C helpers of rocksdb-haskell-jprupp: what the binding needs and the C API
 * of RocksDB does not have.
 *
 * The Haskell imports in Database.RocksDB.C name this header with the capi
 * calling convention, so the C compiler checks each of them against the
 * prototypes below.
 */

#ifndef ROCKSDB_HASKELL_H
#define ROCKSDB_HASKELL_H

#include <stddef.h>
#include <stdint.h>

#include <rocksdb/c.h>

/* Results of the functions below. */
#define ROCKSDB_HASKELL_OK 0
/* of rocksdb_haskell_iter_chunk and rocksdb_haskell_options_set_merge_operator */
#define ROCKSDB_HASKELL_NO_MEMORY 1
/* of rocksdb_haskell_writebatch_add_packed */
#define ROCKSDB_HASKELL_MALFORMED 2

/*
 * Read entries of an iterator, from the one it is on, in one call.
 *
 * Why: a Haskell program pays for every foreign call that may block, so a
 * scan that calls rocksdb_iter_next once for each entry pays once for each
 * entry. This function walks the iterator in C and copies the entries out,
 * so that the scan pays once for a few hundred.
 *
 * It goes forwards with rocksdb_iter_next, or backwards with
 * rocksdb_iter_prev if "backwards" is not zero, and stops at the first of:
 *
 *  - an iterator that is not valid: the end of the data or of its bounds, or
 *    an error;
 *  - an entry whose key does not start with the "prefix_len" bytes at
 *    "prefix" (no bytes: every key does);
 *  - "max_entries" entries read;
 *  - an entry whose key and value would take the bytes of keys and values
 *    read to more than "max_bytes". The first entry is read whatever its
 *    size, so that a scan always moves.
 *
 * The iterator is left on the first entry that was not read. "*more" tells
 * whether that is an entry whose key starts with the prefix: whether there is
 * anything left for another call.
 *
 * "*count" is the number of entries read, and "*buffer" holds them, one
 * after another, each laid out as
 *
 *     size_t key_len; size_t value_len; key bytes; value bytes; padding
 *
 * with padding up to a multiple of sizeof(size_t), so that the lengths are
 * always aligned. The caller frees "*buffer" with free(); it is NULL when no
 * entry was read.
 *
 * Errors:
 *
 *  - An error of the iterator is stored in "*errptr" as by
 *    rocksdb_iter_get_error: a message that the caller frees. Nothing is
 *    returned then: "*buffer" is NULL and "*count" is zero. "*errptr" must be
 *    NULL on entry.
 *  - If memory runs out with some entries read, they are returned as a short
 *    chunk, and the iterator is on the entry that did not fit. If it runs out
 *    on the first entry, the result is ROCKSDB_HASKELL_NO_MEMORY, with
 *    nothing returned and the iterator where it was.
 *
 * The result is ROCKSDB_HASKELL_OK otherwise, also when "*errptr" is set.
 */
int rocksdb_haskell_iter_chunk(
    rocksdb_iterator_t *iter,
    int backwards,
    size_t max_entries,
    size_t max_bytes,
    const char *prefix,
    size_t prefix_len,
    char **buffer,
    size_t *count,
    unsigned char *more,
    char **errptr);

/* The operation of a record of rocksdb_haskell_writebatch_add_packed. */
#define ROCKSDB_HASKELL_PUT 0
#define ROCKSDB_HASKELL_DELETE 1
#define ROCKSDB_HASKELL_MERGE 2

/*
 * The bytes that come before the key of such a record: a column family
 * handle, two lengths and an operation.
 */
#define ROCKSDB_HASKELL_RECORD_HEADER \
    (sizeof(rocksdb_column_family_handle_t *) + 2 * sizeof(uint32_t) + 1)

/*
 * Add many operations to a write batch in one call.
 *
 * Why: a Haskell program pays for every foreign call that may block, so a
 * batch that is built with rocksdb_writebatch_put_cf pays once for each
 * key. For the 65,000 keys of a Bitcoin block that was more than half of
 * the time that the batch took to write, and nearly all of it when other
 * threads of the program were busy: bench/Batch.hs. This function takes
 * the operations packed one after another in a buffer and makes those
 * calls from C, so that the program pays once for a few thousand.
 *
 * "records" holds "len" bytes: any number of records, with nothing between
 * them and nothing after the last. A record is
 *
 *     rocksdb_column_family_handle_t *family;   NULL: the default one
 *     uint32_t key_len;
 *     uint32_t value_len;                       zero for a delete
 *     unsigned char operation;                  ROCKSDB_HASKELL_PUT, ...
 *     key bytes; value bytes
 *
 * with no padding anywhere: the header is ROCKSDB_HASKELL_RECORD_HEADER
 * bytes, 17 where a pointer has eight, and nothing in it is aligned. The
 * handle and the lengths are as this machine holds them in memory, written
 * with memcpy or its like. Being unaligned is what lets a program write a
 * record where the last one ended, in a buffer of its own, and fill in the
 * lengths once it has serialised the key and the value after the header.
 *
 * The operations are added in the order of the records, each as the
 * function of RocksDB that it names would add it: rocksdb_writebatch_put,
 * rocksdb_writebatch_delete or rocksdb_writebatch_merge for the default
 * column family, and the ones ending in _cf for a handle. RocksDB copies
 * the keys and values, so the buffer is not needed after the call.
 *
 * A merge is only added here. Whether the column family has a merge
 * operator to apply it with is for RocksDB to say, when the batch is
 * written or when the key is read.
 *
 * The buffer is checked before anything is added, and the call never reads
 * outside it. If a record is cut short by the end of the buffer, names an
 * operation that does not exist, or is a delete with a value, the result is
 * ROCKSDB_HASKELL_MALFORMED, the batch is as it was, and "*count" is the
 * number of whole records before the bad one. A handle cannot be checked:
 * one that is not NULL has to be a column family of the database that the
 * batch is written to.
 *
 * The result is ROCKSDB_HASKELL_OK otherwise, and "*count" is the number of
 * operations added.
 */
int rocksdb_haskell_writebatch_add_packed(
    rocksdb_writebatch_t *batch,
    const char *records,
    size_t len,
    size_t *count);

/*
 * The two functions of a merge operator, with the types that
 * rocksdb_mergeoperator_create of rocksdb/c.h asks for.
 *
 * The first argument of both is the state of the operator, which belongs
 * to rocksdb_haskell_options_set_merge_operator: a function must not use
 * it. "key" is the key that is merged, for an operator that needs it.
 *
 * A full merge works out the value of a key: from the value that the key
 * has ("existing_value", which is NULL when it has none) and the
 * "num_operands" merge records written since, oldest first, at
 * "operands_list" with their lengths at "operands_list_length".
 *
 * A partial merge is given merge records only, oldest first, and makes one
 * record of them that does to any value what they did one after another.
 * RocksDB uses it to shorten the list before the value is known, when it
 * compacts files that do not have it.
 *
 * Both return the new bytes in memory from malloc(), which RocksDB frees
 * with free(), their length in "*new_value_length", and 1 in "*success".
 * To fail, a function stores 0 in "*success" and in "*new_value_length",
 * and returns NULL: RocksDB copies that many bytes from the result before
 * it looks at "*success". A read of the key then fails, and so does a
 * compaction that meets it. A partial merge that fails is not an error:
 * RocksDB keeps the records as they are.
 *
 * They are called from the threads of RocksDB, during reads, flushes and
 * compactions, several at a time. They must be plain C: a function that
 * enters the Haskell run-time system from such a thread is not what this
 * is for.
 */
typedef char *(*rocksdb_haskell_full_merge_t)(
    void *state,
    const char *key,
    size_t key_length,
    const char *existing_value,
    size_t existing_value_length,
    const char *const *operands_list,
    const size_t *operands_list_length,
    int num_operands,
    unsigned char *success,
    size_t *new_value_length);

typedef char *(*rocksdb_haskell_partial_merge_t)(
    void *state,
    const char *key,
    size_t key_length,
    const char *const *operands_list,
    const size_t *operands_list_length,
    int num_operands,
    unsigned char *success,
    size_t *new_value_length);

/*
 * Give the options of a database or of a column family a merge operator
 * made of a name and two functions.
 *
 * Why: rocksdb_mergeoperator_create wants a state with a destructor and a
 * function that returns the name, besides the two that merge. A Haskell
 * program has no C function to give for those, and should not make one
 * that calls back into Haskell, since RocksDB calls them from its own
 * threads. This function makes the operator around a copy of the name,
 * which is all the state it has and is freed with the operator.
 *
 * The options own the operator from then on, and the column families
 * opened with them keep it for as long as they need it: there is nothing
 * for the caller to destroy. RocksDB frees what the two functions return
 * with free(), since the operator is made without a function of its own
 * for that.
 *
 * The result is ROCKSDB_HASKELL_OK, or ROCKSDB_HASKELL_NO_MEMORY with the
 * options as they were.
 */
int rocksdb_haskell_options_set_merge_operator(
    rocksdb_options_t *options,
    const char *name,
    rocksdb_haskell_full_merge_t full_merge,
    rocksdb_haskell_partial_merge_t partial_merge);

#endif