diff --git a/.gitignore b/.gitignore index bff94d93e..9625b0253 100644 --- a/.gitignore +++ b/.gitignore @@ -41,6 +41,7 @@ CMakeCache.txt cmake_install.cmake CMakeFiles build/ +target/ build_debug/ build_release/ tmp/ diff --git a/.vscode/c_cpp_properties.json b/.vscode/c_cpp_properties.json index cdea37608..505884c2b 100644 --- a/.vscode/c_cpp_properties.json +++ b/.vscode/c_cpp_properties.json @@ -2,7 +2,11 @@ "configurations": [ { "name": "Linux", - "configurationProvider": "ms-vscode.cmake-tools" + "configurationProvider": "ms-vscode.cmake-tools", + "includePath": [ + "${default}", + "${workspaceFolder}/include" + ] } ], "version": 4 diff --git a/go-ukv b/go-ukv index d0791fee0..5fd7bf06b 160000 --- a/go-ukv +++ b/go-ukv @@ -1 +1 @@ -Subproject commit d0791fee0f153e85b5be17433f44bf90cec4f236 +Subproject commit 5fd7bf06bc8e6de982f08966a12b56338911772b diff --git a/rust/.clippy.toml b/rust/.clippy.toml new file mode 100644 index 000000000..991769fde --- /dev/null +++ b/rust/.clippy.toml @@ -0,0 +1,6 @@ +# Right now we just use the defaults. This file exists should we +# want to change that, and to indicate to contributors that they +# might want to run clippy. +# +# See https://rust-lang.github.io/rust-clippy/master/index.html for +# the complete list of lints. \ No newline at end of file diff --git a/rust/.editorconfig b/rust/.editorconfig new file mode 100644 index 000000000..476dd162b --- /dev/null +++ b/rust/.editorconfig @@ -0,0 +1,20 @@ +# EditorConfig coding styles definitions. For more information about the +# properties used in this file, please see the EditorConfig documentation: +# http://editorconfig.org/ + +root = true + +[*] +charset = utf-8 +end_of_line = LF +indent_size = 4 +indent_style = tab +insert_final_newline = true +trim_trailing_whitespace = true + +[*.{yml,json}] +indent_size = 2 +indent_style = space + +[*.{md,diff}] +trim_trailing_whitespace = false diff --git a/rust/CHANGELOG.md b/rust/CHANGELOG.md new file mode 100644 index 000000000..17b1dff65 --- /dev/null +++ b/rust/CHANGELOG.md @@ -0,0 +1,25 @@ +# CHANGELOG + +## 26-01-2023 + +### Contributors + +- chungquantin + +### Added + +- Database structure + +```rs +struct Database { + db: UkvDatabaseInitType +} +``` + +- Build bindings to `cpp` header file in `include/ukv`. To generate bindings code stored, use `cargo build`. `build.rs` includes code to build bindings using `bindgen` +- Support two APIs: `ukv_database_init` and `ukv_database_free` +- Add clippy, rust-fmt and editor config file for formatting and linting + +### Issues + +- Can't generate bindings on file with linked source header. For example, generate on file `blobs.h` which includes `ukv/db.h` would throw error `No header file found`. diff --git a/rust/Cargo.lock b/rust/Cargo.lock new file mode 100644 index 000000000..dc736d1ef --- /dev/null +++ b/rust/Cargo.lock @@ -0,0 +1,285 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 3 + +[[package]] +name = "bindgen" +version = "0.63.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "36d860121800b2a9a94f9b5604b332d5cffb234ce17609ea479d723dbc9d3885" +dependencies = [ + "bitflags", + "cexpr", + "clang-sys", + "lazy_static", + "lazycell", + "log", + "peeking_take_while", + "proc-macro2", + "quote", + "regex", + "rustc-hash", + "shlex", + "syn", + "which", +] + +[[package]] +name = "bitflags" +version = "1.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" + +[[package]] +name = "cc" +version = "1.0.78" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a20104e2335ce8a659d6dd92a51a767a0c062599c73b343fd152cb401e828c3d" + +[[package]] +name = "cexpr" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766" +dependencies = [ + "nom", +] + +[[package]] +name = "cfg-if" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" + +[[package]] +name = "clang-sys" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa2e27ae6ab525c3d369ded447057bca5438d86dc3a68f6faafb8269ba82ebf3" +dependencies = [ + "glob", + "libc", + "libloading", +] + +[[package]] +name = "cmake" +version = "0.1.49" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db34956e100b30725f2eb215f90d4871051239535632f84fea3bc92722c66b7c" +dependencies = [ + "cc", +] + +[[package]] +name = "either" +version = "1.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7fcaabb2fef8c910e7f4c7ce9f67a1283a1715879a7c230ca9d6d1ae31f16d91" + +[[package]] +name = "fs_extra" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2022715d62ab30faffd124d40b76f4134a550a87792276512b18d63272333394" + +[[package]] +name = "glob" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2fabcfbdc87f4758337ca535fb41a6d701b65693ce38287d856d1674551ec9b" + +[[package]] +name = "hermit-abi" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee512640fe35acbfb4bb779db6f0d80704c2cacfa2e39b601ef3e3f47d1ae4c7" +dependencies = [ + "libc", +] + +[[package]] +name = "lazy_static" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646" + +[[package]] +name = "lazycell" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "830d08ce1d1d941e6b30645f1a0eb5643013d835ce3779a5fc208261dbe10f55" + +[[package]] +name = "libc" +version = "0.2.139" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "201de327520df007757c1f0adce6e827fe8562fbc28bfd9c15571c66ca1f5f79" + +[[package]] +name = "libloading" +version = "0.7.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67380fd3b2fbe7527a606e18729d21c6f3951633d0500574c4dc22d2d638b9f" +dependencies = [ + "cfg-if", + "winapi", +] + +[[package]] +name = "log" +version = "0.4.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "abb12e687cfb44aa40f41fc3978ef76448f9b6038cad6aef4259d3c095a2382e" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "memchr" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2dffe52ecf27772e601905b7522cb4ef790d2cc203488bbd0e2fe85fcb74566d" + +[[package]] +name = "minimal-lexical" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a" + +[[package]] +name = "nom" +version = "7.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a" +dependencies = [ + "memchr", + "minimal-lexical", +] + +[[package]] +name = "num_cpus" +version = "1.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fac9e2da13b5eb447a6ce3d392f23a29d8694bff781bf03a16cd9ac8697593b" +dependencies = [ + "hermit-abi", + "libc", +] + +[[package]] +name = "once_cell" +version = "1.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6f61fba1741ea2b3d6a1e3178721804bb716a68a6aeba1149b5d52e3d464ea66" + +[[package]] +name = "peeking_take_while" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19b17cddbe7ec3f8bc800887bab5e717348c95ea2ca0b1bf0837fb964dc67099" + +[[package]] +name = "proc-macro2" +version = "1.0.50" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ef7d57beacfaf2d8aee5937dab7b7f28de3cb8b1828479bb5de2a7106f2bae2" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8856d8364d252a14d474036ea1358d63c9e6965c8e5c1885c18f73d70bff9c7b" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "regex" +version = "1.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48aaa5748ba571fb95cd2c85c09f629215d3a6ece942baa100950af03a34f733" +dependencies = [ + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.6.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "456c603be3e8d448b072f410900c09faf164fbce2d480456f50eea6e25f9c848" + +[[package]] +name = "rustc-hash" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2" + +[[package]] +name = "shlex" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43b2853a4d09f215c24cc5489c992ce46052d359b5109343cbafbf26bc62f8a3" + +[[package]] +name = "syn" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1f4064b5b16e03ae50984a5a8ed5d4f8803e6bc1fd170a3cda91a1be4b18e3f5" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "ukv" +version = "0.0.1" +dependencies = [ + "bindgen", + "cmake", + "fs_extra", + "num_cpus", +] + +[[package]] +name = "unicode-ident" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "84a22b9f218b40614adcb3f4ff08b703773ad44fa9423e4e0d346d5db86e4ebc" + +[[package]] +name = "which" +version = "4.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2441c784c52b289a054b7201fc93253e288f094e2f4be9058343127c4226a269" +dependencies = [ + "either", + "libc", + "once_cell", +] + +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" diff --git a/rust/Cargo.toml b/rust/Cargo.toml new file mode 100644 index 000000000..82dda4a07 --- /dev/null +++ b/rust/Cargo.toml @@ -0,0 +1,33 @@ +[package] +name = "ukv" +version = "0.0.1" +publish = true +edition = "2021" +readme = "CARGO.md" +homepage = "https://github.com/unum-cloud/ukv" +repository = "https://github.com/unum-cloud/ukv" +documentation = "https://unum.cloud/ukv/rust/index.html" + +[build-dependencies] +bindgen = "0.63.0" +cmake = "0.1.49" +fs_extra = "1.2.0" +num_cpus = "1.15.0" + +[lib] +name = "ukv" + +[features] +# Features for different backend implementations +# Library filenames: +# - libukv_embedded_umem +# - libukv_embedded_leveldb +# - libukv_embedded_rocksdb +# - libukv_flight_client +umem = [] +leveldb = [] +rocksdb = [] +flight-server = [] +flight-client = [] +default = ["umem"] + diff --git a/rust/README.md b/rust/README.md index 99655bf5d..18833eead 100644 --- a/rust/README.md +++ b/rust/README.md @@ -2,10 +2,12 @@ Rust implementation is designed to support: -* Named Collections -* ACID Transactions -* Single & Batch Operations -* [Apache DataFusion](https://arrow.apache.org/datafusion/) `TableProvider` for SQL +- Named Collections +- ACID Transactions +- Single & Batch Operations +- [Apache DataFusion](https://arrow.apache.org/datafusion/) `TableProvider` for SQL +- Tabular operation with [Polars](https://www.pola.rs/) and integration with [`Apache Arrow`](https://pola-rs.github.io/polars-book/user-guide/howcani/interop/arrow.html) +- NetworkX compatibility using [RustworkX](https://github.com/Qiskit/rustworkx) Using it should be, again, familiar, as it mimics [`std::collections`](https://doc.rust-lang.org/std/collections/hash_map/struct.HashMap.html): diff --git a/rust/build.rs b/rust/build.rs new file mode 100644 index 000000000..57be72841 --- /dev/null +++ b/rust/build.rs @@ -0,0 +1,125 @@ +extern crate bindgen; +extern crate cmake; +extern crate num_cpus; + +use std::path::PathBuf; + +/// Gets the absolute path of the parent directory. This will be used for +/// specifying the cmake directory and linking the library files from there. +fn get_parent_dir() -> std::io::Result { + let path = std::env::current_dir().unwrap(); + let path = format!("{}/../", path.as_os_str().to_string_lossy()); + let path = PathBuf::from(path); + let path = path.canonicalize().unwrap(); + let path = path.as_os_str(); + Ok(format!("{}", path.to_string_lossy())) +} + +const ENABLED: &'static str = "1"; +const DISABLED: &'static str = "0"; + +fn main() { + let makeflags = format!("-j{}", num_cpus::get()); + std::env::set_var("CARGO_MAKEFLAGS", &makeflags); + std::env::set_var("MAKEFLAGS", makeflags); + + let parent_dir = get_parent_dir().unwrap(); + let dst = cmake::Config::new(&parent_dir) + .define( + "UKV_BUILD_ENGINE_UMEM", + if cfg!(feature = "umem") { + ENABLED + } else { + DISABLED + }, + ) + .define( + "UKV_BUILD_ENGINE_LEVELDB", + if cfg!(feature = "leveldb") { + ENABLED + } else { + DISABLED + }, + ) + .define( + "UKV_BUILD_ENGINE_ROCKSDB", + if cfg!(feature = "rocksdb") { + ENABLED + } else { + DISABLED + }, + ) + .define( + "UKV_BUILD_API_FLIGHT_CLIENT", + if cfg!(feature = "flight-client") { + ENABLED + } else { + DISABLED + }, + ) + .define( + "UKV_BUILD_API_FLIGHT_SERVER", + if cfg!(feature = "flight-server") { + ENABLED + } else { + DISABLED + }, + ) + .define( + "CMAKE_BUILD_TYPE", + if std::env::var("PROFILE").unwrap() == "release" { + "Release" + } else { + "Debug" + }, + ) + .define("UKV_BUILD_TESTS", DISABLED) + .define("UKV_BUILD_BENCHMARKS", DISABLED) + .build(); + + println!("cargo:rustc-link-search=native={}", dst.display()); + + #[cfg(feature = "umem")] + println!("cargo:rustc-link-lib=ukv_embedded_umem"); + + #[cfg(feature = "rocksdb")] + println!("cargo:rustc-link-lib=ukv_embedded_rocksdb"); + + #[cfg(feature = "leveldb")] + println!("cargo:rustc-link-lib=ukv_embedded_leveldb"); + + #[cfg(feature = "flight-client")] + println!("cargo:rustc-link-lib=ukv_flight_client"); + + #[cfg(feature = "flight-server")] + println!("cargo:rustc-link-lib=ukv_flight_server"); + + let output = PathBuf::from(std::env::var("OUT_DIR").unwrap()); + fs_extra::copy_items( + &[format!("{}/include", parent_dir).as_str()], + output.display().to_string().as_str(), // no need to include `include/`, since the whole + // directory is going to be copied. + &fs_extra::dir::CopyOptions { + depth: 0, // unlimited + overwrite: true, + skip_exist: true, + copy_inside: false, + content_only: false, + buffer_size: 64_000, + }, + ) + .unwrap(); + drop(parent_dir); + + let bindings = bindgen::Builder::default() + .header("wrapper.h") + .size_t_is_usize(true) + .detect_include_paths(true) + .parse_callbacks(Box::new(bindgen::CargoCallbacks)) + .clang_arg(format!("-I{}/include/", dst.display())) + .clang_arg(format!("-I{}/include/ukv", dst.display())) + .generate() + .unwrap(); + bindings.write_to_file(output.join("bindings.rs")).unwrap(); + eprintln!("{}", output.display()); // printing in the end for debugging purposes +} diff --git a/rust/rustfmt.toml b/rust/rustfmt.toml new file mode 100644 index 000000000..dc2e24ce3 --- /dev/null +++ b/rust/rustfmt.toml @@ -0,0 +1,17 @@ +edition = "2021" +hard_tabs = true +merge_derives = true +reorder_imports = true +reorder_modules = true +use_field_init_shorthand = true +use_small_heuristics = "Off" + +# ----------------------------------- +# Unstable options we would like to use in future +# ----------------------------------- + +#blank_lines_lower_bound = 1 +#indent_style = "Block" +#match_arm_blocks = true +#reorder_impl_items = true +#wrap_comments = true \ No newline at end of file diff --git a/rust/src/error.rs b/rust/src/error.rs new file mode 100644 index 000000000..37a741acc --- /dev/null +++ b/rust/src/error.rs @@ -0,0 +1,7 @@ +use thiserror::Error; + +#[derive(Error, Debug)] +pub enum DataStoreError { + #[error("unknown data store error")] + Unknown, +} diff --git a/rust/src/lib.rs b/rust/src/lib.rs new file mode 100644 index 000000000..b5229e388 --- /dev/null +++ b/rust/src/lib.rs @@ -0,0 +1,95 @@ +#![allow(non_upper_case_globals)] +#![allow(non_camel_case_types)] +#![allow(non_snake_case)] + +/// Aliased type for any errors related to ukv. Since the type +/// of [bindings::ukv_error_t] is a raw [std::ffi::c_char] pointer, +/// there is no specific way to track the errors more efficiently. +pub type Error<'a> = std::borrow::Cow<'a, str>; + +/// Bindings generated by bindgen for the ukv library. Only use this +/// module directly if you know what you are doing. +pub mod bindings { + include!(concat!(env!("OUT_DIR"), "/bindings.rs")); +} + +/// Provides a safe interface for working with [bindings::ukv_database_init_t]. +#[derive(Debug)] +pub struct Database { + /// Internal object will be used for safely interfacing with the + /// C/C++ bindings via a Rust-defined interface. + inner: bindings::ukv_database_init_t, +} + +/// Provides a _fallible_ initialization interface for [Database]. Prefer +/// using [Database::new] for error-safe initialization. You should always +/// check for errors after initialization by calling [Database::error] in +/// case something fails. +impl Default for Database { + fn default() -> Self { + let mut inner = bindings::ukv_database_init_t { + db: &mut () as *mut _ as *mut std::ffi::c_void as _, + config: std::ffi::CString::default().as_ptr() as *const _, + error: &mut std::ffi::CString::default().as_ptr() as *mut _, + }; + + unsafe { bindings::ukv_database_init(&mut inner) }; + Self { + inner, + } + } +} + +impl<'a> Database { + /// Creates a new [Database] instance. In case of errors, the + /// function will return [Error]. + pub fn new() -> Result> { + let initialized: Database = Default::default(); + initialized.error()?; + Ok(initialized) + } + + /// Checks whether there are any errors created by the database, + /// and returns the pointer to the error. + pub fn error(&self) -> Result<(), Error<'a>> { + if !self.inner.error.is_null() { + // We know that `error` is going to be a valid pointer, pointing to a + // std::ffi::CString, thus, dereferencing the pointer here is safe. + let message = unsafe { std::ffi::CStr::from_ptr(*self.inner.error) }; + return Err(String::from_utf8_lossy(message.to_bytes())); + } + + Ok(()) + } + + /// Closes a [Database] instance. In case of errors, the function + /// will return [Error]. + #[inline] + pub fn close(self) -> Result<(), Error<'a>> { + // We know that `self.inner.db` is going to point to a valid address + // in memory, thus, dereferencing the pointer here is safe. + unsafe { bindings::ukv_database_free(*self.inner.db) }; + Ok(self.error()?) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_Database_new() { + assert!(Database::new().is_ok()); + } + + #[test] + fn test_Database_default() { + assert!(Database::default().error().is_ok()) + } + + #[test] + fn test_Database_close() { + let database = Database::new().expect("Cannot initialize the database"); + assert!(database.close().is_ok()) + } +} diff --git a/rust/wrapper.h b/rust/wrapper.h new file mode 100644 index 000000000..c6ac8f456 --- /dev/null +++ b/rust/wrapper.h @@ -0,0 +1,8 @@ +#include +#include +#include +#include +#include +#include +#include +#include