Crate yottadb

YottaDB is a NoSQL Database suitable for high-performance systems.

YottaDB runs in-process, like SQLite, with no need for a daemon. This crate is a Rust wrapper around the C implementation of YottaDB.

There are two major APIs:

• craw, the FFI bindings generated directly by bindgen. These are not recommended for normal use, but are available in case the Context API is missing functionality.
• The main Context API, which is a safe wrapper around the C API which stores the current tptoken and an error buffer so you don’t have to keep track of them yourself. The reason this metadata is necessary is because this crate binds to the threaded version of YottaDB, which requires a tptoken and err_buffer. See transaction processing for more details on transactions and tptokens.

Most operations are encapsulated in methods in the KeyContext struct. Iteration helpers are available to iterate over values in the database in a variety of ways.

Examples

A basic database operation (set a value, retrieve it, and delete it)

use yottadb::{Context, KeyContext, DeleteType, YDBResult};

fn main() -> YDBResult<()> {
    let ctx = Context::new();
    let mut key = KeyContext::new(&ctx, "^MyGlobal", &["SubscriptA", "42"]);
    key.set("This is a persistent message")?;
    let buffer = key.get()?;
    assert_eq!(&buffer, b"This is a persistent message");
    key.delete(DeleteType::DelNode)?;
    Ok(())
}

Intrinsic Variables

YottaDB has several intrinsic variables which are documented online. To get the value of these variables, call get_st on a Key with the name of the variable.

Example

Get the instrinsic variable $tlevel, which gives the current transaction level.

use yottadb::{Context, KeyContext, YDB_NOTTP, YDBResult};

fn main() -> YDBResult<()> {
    let ctx = Context::new();
    let mut key = KeyContext::variable(&ctx, "$tlevel");
    let tlevel: usize = String::from_utf8_lossy(&key.get()?).parse()
        .expect("$tlevel should be an integer");
    assert_eq!(tlevel, 0_usize);
    Ok(())
}

Features

Since yottadb is a set of bindings to a C library, it uses bindgen to generate the bindings. There are two ways to do this:

• features = ["vendor"], the default. This compiles bindgen from source.
• default-features = false. This requires you to have bindgen already installed locally.

Using vendoring means you can use yottadb in any user environment, even when you don’t have admin priviledges to install programs. Using a pre-installed version means compile times are much lower.

Signal handling

YottaDB performs its own signal handling in addition to any signal handlers you may have set up. Since many functions in C are not async-safe, it defers any action until the next time ydb_eintr_handler is called. All YDB functions will automatically call ydb_eintr_handler if necessary, so in most cases this should not affect your application. However, there are some rare cases when the handler will not be called:

• If you have a tight loop inside a Context::tp that does not call a YDB function

For example, the following loop will run forever even if sent SIGINT:

use yottadb::{Context, KeyContext};
let ctx = Context::new();
let loop_callback = |_| loop {
    std::thread::sleep(std::time::Duration::from_secs(1));
    println!("finished sleep");
};
ctx.tp(loop_callback, "BATCH", &[]).unwrap();

To avoid this, call Context::eintr_handler in the loop:

loop {
    std::thread::sleep(std::time::Duration::from_secs(1));
    ctx.eintr_handler()?;
    println!("finished sleep");
}

However, you should endeavor to keep transactions as short as possible - both for performance, since YottaDB uses optimistic concurrency control, and for reliability, since operations will not be committed until the transaction concludes.

As a last-ditch method of error-recovery, YottaDB will exit immediately if sent three interrupt signals in a row, even if eintr_handler is not called.

YottaDB does not register any signal handlers until the first time ydb_init is called, and deregisters its handlers after ydb_exit.

See also

• The C documentation on signals
• Context::eintr_handler
• Context::tp

Re-exports

• pub use craw::YDB_ERR_GVUNDEF;
• pub use craw::YDB_ERR_LVUNDEF;

Modules

• craw
  A wrapper for C YottaDB API (the C Raw API, CRAW)

Macros

• ci_t
  Make an FFI call to M.
• cip_t
  Make a FFI call to M using a cached function descriptor.
• make_ckey
  Create a KeyContext with the given subscripts, provided a context.
• make_key
  Provides a Key object for the given subscripts.

Structs

• CallInDescriptor
  A call-in descriptor for use with cip_t!.
• CallInTableDescriptor
  The descriptor for a call-in table opened with ci_tab_open.
• Context
  A struct that keeps track of the current transaction and error buffer.
• ForwardKeyNodeIterator
• ForwardKeySubIterator
• ForwardNodeIterator
• ForwardSubIterator
• ForwardSubValueIterator
• ForwardValueIterator
• Key
  A key used to get, set, and delete values in the database.
• KeyContext
  A key which keeps track of the current transaction and error buffer.
• ReverseKeyNodeIterator
• ReverseKeySubIterator
• ReverseNodeIterator
• ReverseSubIterator
• ReverseSubValueIterator
• ReverseValueIterator
• TpToken
  A transaction processing token, used by yottadb to ensure ACID properties.
• YDBError
  An error returned by the underlying YottaDB library.

Enums

• DataReturn
  The type of data available at the current node.
• DeleteType
  The type of deletion that should be carried out.
• ParseError
  The error type returned by KeyContext::get_and_parse()
• TransactionStatus
  The status returned from a callback passed to Context::tp

Constants

• YDB_NOTTP
  The default transaction processing token if no transaction is in progress.

Functions

• ydb_exit
  Cleans up the process connection/access to all databases and all yottadb data structures.

Type Aliases

• YDBResult
  A specialized Result type returned by a YottaDB function.