Module api

Expand description

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_enum: Constructor of q enum object. This is a complememtal constructor of missing second type.
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 Aliases§

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.

Module api

Module api Copy item path

§Examples

Modules§

Structs§

Constants§

Traits§

Functions§

Type Aliases§

Unions§

Module api