Crate kdb[−][src]

Expand description

rust-kdb is an idiomatic Rust wrapper around the KDB+ C API. It supports manipulating K objects efficiently using zero cost abstractions, conversion to and from rust native types, and creation and editing of K lists/dictionaries using iterators.

The design goals of the library:

  1. Performance
  2. Provide an idiomatic rust API
  3. Safety

Why you might like it

  1. It’s really fast. The abstractions around the KDB types have zero overhead so while it feels like you are using rust types with all the trimmings, it is as fast as calling the raw C API directly.
  2. It’s safe! Using the C API is full of pitfalls that cause undefined behaviour. The abstractions in rust-kdb manage these for you, so that you don’t need to worry about freeing your KDB objects or weird behaviour.
  3. It’s just like using other rust data types. We’ve worked hard to make Lists work like Rust vectors, and to add similar convenience functions to dictionaries.

Why you might not like it

  1. Type conversions are common. It’s not unusual to see rust-kdb code littered with .try_into().unwrap() Especially when working with mixed lists. This is a consequence of retrofitting the kdb type system into Rust. These type conversions are cheap (from/into are free, try_from/try_into are a single check of the KDB type code) But they do dirty the code somewhat.
  2. It’s incomplete. It currently lacks support for tables and not all functions have been included. The plan is to include these features in time.

Creating KDB types

KDB deals with atoms and lists. rust-kdb maps this to the Atom And List generic types. We create a kdb type using a KBox. Just like a Rust Box wraps Rust heap managed pointers, KBox wraps KDB managed pointers.

To create a new 32-bit integer atom:

use kdb::KBox;
let a = KBox::new_atom(42);
assert_eq!(a.value(), 42);

To create a list of bytes:

let mut l = KBox::<List<u8>>::new_list();
for i in 1..=10 {
    l.push(i);   
}
assert_eq!(l.len(), 10);

Working with unknown types

KDB is dynamically typed, in that each type is an instance of a k object This is similar to variant types in C++. In rust-kdb, we manage this with the Any type.

The Any type can be used in place of any valid KDB value (atom or list). You can’t do much with it, except try to convert it to a different type, using the cast! and try_cast! macros.

use kdb::{cast, Any, Atom, KBox};

let a = KBox::new_atom(42);
let b: KBox<Any> = a.into();
let c = cast!(b; Atom<i32>);

Writing embedded KDB plug-ins

Writing embedded plugins is straightforward using rust-kdb. Youll need to use the “embedded” feature for your plugin to use the correct library bindings.

Below is an example of a simple KDB plugin

use kdb::*;
use std::convert::TryFrom;
use std::f64::consts::PI;

/// Calculates the circumference of a circle. Returns a null value if the radius is not a real number.
#[no_mangle]
pub extern "C" fn circumference(radius: &Any) -> Option<KBox<Atom<f64>>> {
    if let Ok(r) = try_cast!(radius; Atom<f64>) {
        return Some(KBox::new_atom(r.value() * r.value() * PI));
    }
    None
}

Key points:

  1. Note that KDB parameters in extern “C” functions are references to KDB types, rather than a KBox. In KDB, the caller owns the parameters. Using a KBox here will likely cause a segfault.
  2. The return type is always either a KBox or Option<KBox>. This is equivalent to returning a K pointer. Always return an owned type.
  3. You can use typed atoms for parameters, not just Any. Bear in mind that this is unsafe as it is possible for q code to call the function with a type other than that one. Any is always safest.

Re-exports

pub use array_iterator;
pub use uuid;

Modules

kapi

Provides ffi definitions for the KDB C API.

Macros

cast

Cast a KBox, &KBox or &Any to another KDB type.

list

Create a list from a set of supplied values.

try_cast

Tries to cast a KBox, &KBox or &Any to another KDB type.

Structs

Any

Any represents any KDB value regardless of type. Unlike atoms or lists you can’t do anything with it, except for convert it into an atom or a list. It is ABI compatible with a K object, so it can be safely used as a parameter or return type for a function. See the chapter on embedded functions for more information.

Atom

Atoms are the base primitive values in rust-kdb. You can create a new atom by calling KBox::new_atom, or using the From/Into traits on a value.

Connection

Represents a connection to a remote or embedded KDB instance, which can be used to send and query data on that instance.

Date

Represents the number of days since 1 Jan 2000.

DateTime

Represents a date and time in KDB. Conversions between the Unix Epoch and the KDB Epoch are done automatically.

Dictionary

A key value based dictionary.

KBox

Represents a memory managed K pointer. They are the KDB equivalent of a Rust Box, a zero overhead wrapper around a K pointer. It will call r0 to decrement the reference count when it is dropped.

KError

Represents an error in KDB.

List

Lists are the KDB equivalent of Rust’s Vec. They contain collections of values and their contents be looked up by index.

Minute

Represents the number of minutes since midnight (00:00).

Month

The number of months since January 2000.

Second

Represents the number of seconds since midnight (00:00)

Symbol

Represents a KDB Symbol (interned string) Implements basic symbol operations for efficiency Can be converted to/from strings

Table

Represents a table (a dictionary of columns) in KDB

Time

The number of milliseconds since midnight.

Timespan

Represents an elapsed span of time

Timestamp

Represents a timestamp in KDB. Conversions between the Unix Epoch and the KDB Epoch are done automatically.

Enums

ConnectionError

The error type for connecting to KDB.

ConversionError

Error type for converting from/to kdb types.

Error

The error type for Q query execution.

SerializationMode

Describes how to perform serialization when using b9_serialize.

Functions

b9_serialize

Serialize a K object using KDB serialization.

d9_deserialize

Decode a serialized K object.

init

[not-embedded] Initialize the kdb memory subsystem. this is required when using generator functions in a standalone kdb application. This is equivalent to calling khp("", -1) in the C api.

register_callback

Registers a callback function to be called when data is available on a particular file descriptor. Equivalent to calling sd1(fd, cb) in the C API.

remove_callback

Removes a callback registered on the specified file descriptor with the register_callback function

symbol

Helper for succinctly creating a symbol. If the string passed in is not a valid symbol, i.e. it contains embedded nuls, then this function will panic.

Type Definitions

Callback

Callback for using in the set_callback function.