Module kdbplus::api [−][src]
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 undernative
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_simple_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.error_to_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_simple_list(qtype::SYMBOL_LIST, 2); let keys_slice=keys.as_mut_slice::<S>(); keys_slice[0]=internalize(str_to_S!("time")); keys_slice[1]=internalize_n(str_to_S!("temperature_and_humidity"), 11); // Build values let values=new_simple_list(qtype::COMPOUND_LIST, 2); let time=new_simple_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_simple_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
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
Struct representing 16-bytes GUID.
Underlying struct of K
object.
Underlying list value of q object.
Constants
K
nullptr. This value is used as void value of a function which returns K
.
Traits
Functions
Convert S
to &str
. This function is intended to convert symbol type (null-terminated char-array) to str
.
Apply a function to q list object .[func; args]
.
Convert the number of days from 2000.01.01
to a number expressed as yyyymmdd
.
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.
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
.
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 Rust object inside q. Passed as the first element of a foreign object.
Constructor of q keyed table object.
Convert an error object into usual K
object which has the error string in the field symbol
.
Constructor of q table object from a q dictionary object.
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.
Intern a null-terminated char array. Returns an interned char array and should be used to add char array to a symbol vector.
Intern n
chars from a char array.
Returns an interned char array and should be used to add char array to a symbol vector.
Judge if a catched object by error_to_string
is a genuine error object of type
qtype::ERROR
(This means false positive of the case KNULL
is eliminated).
Load C function as a q function (K
object).
Constructor of q bool object. Relabeling of kb
.
Constructor of q byte object. Relabeling of kg
.
Constructor of q char object. Relabeling of kc
.
Constructor of q date object. Relabeling of kd
.
Constructor of q datetime object from the number of days since kdb+ epoch (2000.01.01
). Relabeling of kz
.
Constructor of q dictionary object.
Constructor of q error. The input must be null-terminated.
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.
Constructor of q float object. Relabeling of kf
.
Constructor of q GUID object. Relabeling of ku
.
Constructor of q int object. Relabeling of ki
.
Constructor of q long object. Relabeling of kj
.
Create a month object. This is a complememtal constructor of missing minute type.
Create a month object from the number of months since kdb+ epoch (2000.01.01
).
This is a complememtal constructor of missing month type.
Constructor of q general null.
Constructor of q real object. Relabeling of ke
.
Create a month object. This is a complememtal constructor of missing second type.
Constructor of q short object. Relabeling of kh
.
Constructor of q simple list.
Constructor of q string object.
Constructor if q string object with a fixed length.
Constructor of q symbol object. Relabeling of ks
.
Constructor of q time object. Relabeling of kt
.
Constructor of q timespan object from nanoseconds. Relabeling of ktj
.
Constructor of q timestamp from elapsed time in nanoseconds since kdb+ epoch (2000.01.01
). Relabeling of ktj
.
Convert null-terminated &str
to S
.
Convert null terminated &str
into const_S
. Expected usage is to build
a q error object with krr
.
Lock a location of internalized symbol in remote threads. Returns the previously set value.
Register callback to the associated kdb+ socket.
Constructor of simple q table object from a q keyed table object.
Unlock a location of internalized symbol in remote threads.
Convert ymd to the number of days from 2000.01.01
.
Type Definitions
char
in C. Also used to access char of q.
f32
in C. Also used to access real of q.
f64
in C. Also used to access float and datetime of q.
unsigned char
in C. Also used to access byte of q.
i16
in C. Also used to access short of q.
i32
in C. Also used to access int and compatible types (month, date, minute, second and time) of q.
i64
in C. Also used to access long and compatible types (timestamp and timespan) of q.
Struct representing q object.
char*
in C. Also used to access symbol of q.
void
in C.
const char*
in C.
Unions
Underlying atom value of q object.