Module kdbplus::api

This api module provides API mirroring the C API of q/kdb+. The expected usage is to build a shared library for q/kdb+ in Rust.

In order to avoid writing too large unsafe block leading to poor optimization, most of native C API functions were provided with a wrapper funtion with a bit of ergonomic safety and with intuitive implementation as a trait method. The only exceptions are:

• knk
• k These functions are using elipsis (...) as its argument and cannot be provided with a stable distribution. When you need to use either of them you can find them under native namespace together with the other naked C API functions.

Notes:

• This library is for kdb+ version >= 3.0.
• Meangless C macros are excluded but accessors of an underlying array like kC, kJ, kK etc. are provided in Rust way.

Examples

In order to encourage to use Rust style API, examples of the C API style is not provided here (you can see them in README of the repository). The examples below are written without unsafe code. You can see how comfortably breathing are the wrapped functions in the code.

#[macro_use]
extern crate kdbplus;
use kdbplus::api::*;
use kdbplus::qtype;
 
#[no_mangle]
pub extern "C" fn create_symbol_list2(_: K) -> K{
  let mut list=new_list(qtype::SYMBOL_LIST, 0);
  list.push_symbol("Abraham").unwrap();
  list.push_symbol("Isaac").unwrap();
  list.push_symbol("Jacob").unwrap();
  list.push_symbol_n("Josephine", 6).unwrap();
  list
}
 
#[no_mangle]
fn no_panick(func: K, args: K) -> K{
  let result=error_to_string(apply(func, args));
  if let Ok(error) = result.get_error_string(){
    println!("FYI: {}", error);
    // Decrement reference count of the error object which is no longer used.
    decrement_reference_count(result);
    KNULL
  }
  else{
    println!("success!");
    result
  }
}
 
#[no_mangle]
pub extern "C" fn create_table2(_: K) -> K{
  // Build keys
  let keys=new_list(qtype::SYMBOL_LIST, 2);
  let keys_slice=keys.as_mut_slice::<S>();
  keys_slice[0]=enumerate(str_to_S!("time"));
  keys_slice[1]=enumerate_n(str_to_S!("temperature_and_humidity"), 11);
 
  // Build values
  let values=new_list(qtype::COMPOUND_LIST, 2);
  let time=new_list(qtype::TIMESTAMP_LIST, 3);
  // 2003.10.10D02:24:19.167018272 2006.05.24D06:16:49.419710368 2008.08.12D23:12:24.018691392
  time.as_mut_slice::<J>().copy_from_slice(&[119067859167018272_i64, 201766609419710368, 271897944018691392]);
  let temperature=new_list(qtype::FLOAT_LIST, 3);
  temperature.as_mut_slice::<F>().copy_from_slice(&[22.1_f64, 24.7, 30.5]);
  values.as_mut_slice::<K>().copy_from_slice(&[time, temperature]);
   
  flip(new_dictionary(keys, values))
}

And q code is here:

q)summon:`libapi_examples 2: (`create_symbol_list2; 1)
q)summon[]
`Abraham`Isaac`Jacob`Joseph
q)chill: `libapi_examples 2: (`no_panick; 2);
q)chill[$; ("J"; "42")]
success!
42
q)chill[+; (1; `a)]
FYI: type
q)climate_change: libc_api_examples 2: (`create_table2; 1);
q)climate_change[]
time                          temperature
-----------------------------------------
2003.10.10D02:24:19.167018272 22.1       
2006.05.24D06:16:49.419710368 24.7       
2008.08.12D23:12:24.018691392 30.5  

Modules

native

This module exposes bare C API functions. As most of them are provided with a “safe” wrapper function with an intuitive name and intuitive implementation for Rust, there is no gain to darely use these functions.

Structs

U

Struct representing 16-bytes GUID.

k0

Underlying struct of K object.

k0_list

Underlying list value of q object.

Constants

KNULL

K nullptr. This value can be used as void value of a function which is called directly by q process and returns K. This null pointer is interpreted as a general null value (::) whose type is 101h.

Traits

KUtility

Trait which defines utility methods to manipulate q object.

Functions

S_to_str

Convert S to &str. This function is intended to convert symbol type (null-terminated char-array) to str.

apply

Apply a function to q list object .[func; args].

days_to_ymd

Convert the number of days from 2000.01.01 to a number expressed as yyyymmdd.

decrement_reference_count

Decrement reference count of the q object. The decrement must be done when k function gets an error object whose type is qtype::ERROR and when you created an object but do not intend to return it to q side. See details on the reference page.

destroy_socket

Remove callback from the associated kdb+ socket and call kclose. Return null if the socket is invalid or not the one which had been registered by sd1.

destroy_socket_if

Remove callback from the associated kdb+ socket and call kclose if the given condition is satisfied. Return null if the socket is invalid or not the one which had been registered by sd1.

drop_q_object

Drop Rust object inside q. Passed as the first element of a foreign object.

enkey

Constructor of q keyed table object.

enumerate

Enumerate a null-terminated character array internally. This function must be used to add a character array as a symbol value to a symbol list. The returned value is the same character array as the input.

enumerate_n

Extract the first n chars from a character array and enumerate it internally. This function must be used to add a character array as a symbol value to a symbol list. The returned value is the same character array as the input.

error_to_string

Convert an error object into usual K object which has the error string in the field symbol.

flip

Constructor of q table object from a q dictionary object.

increment_reference_count

Increment reference count of the q object. Increment must be done when you passed arguments to Rust function and intends to return it to q side or when you pass some K objects to k function and intend to use the argument after the call. See details on the reference page.

is_error

Judge if a catched object by error_to_string is a genuine error object of type qtype::ERROR (This means false positive of the KNULL case can be eliminated).

load_as_q_function

Load C function as a q function (K object).

new_bool

Constructor of q bool object. Relabeling of kb.

new_byte

Constructor of q byte object. Relabeling of kg.

new_char

Constructor of q char object. Relabeling of kc.

new_date

Constructor of q date object. Relabeling of kd.

new_datetime

Constructor of q datetime object from the number of days since kdb+ epoch (2000.01.01). Relabeling of kz.

new_dictionary

Constructor of q dictionary object.

new_error

Constructor of q error. The input must be null-terminated.

new_error_os

Similar to new_error but this function appends a system-error message to string S before passing it to internal krr. The input must be null-terminated.

new_float

Constructor of q float object. Relabeling of kf.

new_guid

Constructor of q GUID object. Relabeling of ku.

new_int

Constructor of q int object. Relabeling of ki.

new_list

Constructor of q simple list.

new_long

Constructor of q long object. Relabeling of kj.

new_minute

Create a month object. This is a complememtal constructor of missing minute type.

new_month

Create a month object from the number of months since kdb+ epoch (2000.01.01). This is a complememtal constructor of missing month type.

new_null

Constructor of q general null.

new_real

Constructor of q real object. Relabeling of ke.

new_second

Create a month object. This is a complememtal constructor of missing second type.

new_short

Constructor of q short object. Relabeling of kh.

new_string

Constructor of q string object.

new_string_n

Constructor if q string object with a fixed length.

new_symbol

Constructor of q symbol object. Relabeling of ks.

new_time

Constructor of q time object. Relabeling of kt.

new_timespan

Constructor of q timespan object from nanoseconds. Relabeling of ktj.

new_timestamp

Constructor of q timestamp from elapsed time in nanoseconds since kdb+ epoch (2000.01.01). Relabeling of ktj.

null_terminated_str_to_S

Convert null-terminated &str to S.

null_terminated_str_to_const_S

Convert null terminated &str into const_S. Expected usage is to build a q error object with krr.

pin_symbol

Enable the remote threads to refer to the sym list in the main thread so that enumeration of remotely created symbol values reain valid in the main thread after joining the remote threads. This function must be used before starting any other threads if the threads create symbol values. The previously set value is returned.

register_callback

Register callback to the associated kdb+ socket.

simple_to_compound

Convert a simple list to a compound list. Expected usage is to concatinate a simple list with a different type of list.

unkey

Constructor of simple q table object from a q keyed table object.

unpin_symbol

Unlock the symbol list in the main thread. This function should be called after joining threads.

ymd_to_days

Convert ymd to the number of days from 2000.01.01.

Type Definitions

C

char in C. Also used to access char of q.

E

f32 in C. Also used to access real of q.

F

f64 in C. Also used to access float and datetime of q.

G

unsigned char in C. Also used to access byte of q.

H

i16 in C. Also used to access short of q.

I

i32 in C. Also used to access int and compatible types (month, date, minute, second and time) of q.

J

i64 in C. Also used to access long and compatible types (timestamp and timespan) of q.

K

Struct representing q object.

S

char* in C. Also used to access symbol of q.

V

void in C.

const_S

const char* in C.

Unions

k0_inner

Underlying atom value of q object.