mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-09-20 08:40:50 +00:00
74 lines
7.2 KiB
Markdown
74 lines
7.2 KiB
Markdown
---
|
||
sidebar_position: 98
|
||
slug: /ru/development/integrating_rust_libraries
|
||
---
|
||
# Интеграция библиотек на языке Rust в ClickHouse.
|
||
|
||
Интеграция библиотек будет описываться на основе работы проведенной для библиотеки BLAKE3.
|
||
|
||
Первым шагом интеграции является добавление библиотеки в папку /rust. Для этого необходимо создать в папке пустой Rust-проект, подключив в Cargo.toml нужную библиотеку. Также необходимо компилировать новую библиотеку как статическую, для этого необходимо добавить `crate-type = ["staticlib"]` в Cargo.toml.
|
||
|
||
Далее необходимо подключить библиотеку к CMake. Для этого в ClickHouse была подключена библиотека Corrosion. Первым шагом является подключение папки с новой библиотекой в корневом CMakeLists.txt папки /rust. После этого следует добавить в директорию с библиотекой файл CMakeLists.txt, в котором будет вызвана функция из Corrosion. Как пример, приведем файл из BLAKE3:
|
||
|
||
```
|
||
corrosion_import_crate(MANIFEST_PATH Cargo.toml NO_STD)
|
||
|
||
target_include_directories(_ch_rust_blake3 INTERFACE include)
|
||
add_library(ch_rust::blake3 ALIAS _ch_rust_blake3)
|
||
```
|
||
|
||
Таким образом, мы создадим при помощи Corrosion корректный CMake-таргет, а затем переобозначим его более понятным именем. Стоит отметить, что имя `_ch_rust_blake3` происходит из Cargo.toml, где оно выступает в качестве имени проекта (`name = "_ch_rust_blake3"`).
|
||
|
||
|
||
Поскольку типы данных Rust не совместимы с типами данных C/C++, то в проекте мы опишем интерфейс для методов-прослоек, которые будут преобразовывать данные, получаемые из C/C++, вызывать методы библиотеки, а затем делать преобразование возвращаемых обратно данных. В частности, рассмотрим такой метод, написанный для BLAKE3:
|
||
|
||
```
|
||
#[no_mangle]
|
||
pub unsafe extern "C" fn blake3_apply_shim(
|
||
begin: *const c_char,
|
||
_size: u32,
|
||
out_char_data: *mut u8,
|
||
) -> *mut c_char {
|
||
if begin.is_null() {
|
||
let err_str = CString::new("input was a null pointer").unwrap();
|
||
return err_str.into_raw();
|
||
}
|
||
let mut hasher = blake3::Hasher::new();
|
||
let input_bytes = CStr::from_ptr(begin);
|
||
let input_res = input_bytes.to_bytes();
|
||
hasher.update(input_res);
|
||
let mut reader = hasher.finalize_xof();
|
||
reader.fill(std::slice::from_raw_parts_mut(out_char_data, blake3::OUT_LEN));
|
||
std::ptr::null_mut()
|
||
}
|
||
```
|
||
|
||
На вход метод принимает строку в C-совместимом формате, её размер и указатель, в который будет положен результат. Кроме того, для того, чтобы иметь возможность вывести ошибку, метод возвращает строку с ней как результат работы (и нулевой указатель в случае отсутствия ошибок). C-совместимые не используются в методах BLAKE3, поэтому они конвертируются посредством соотвествующих структур и методов в привычные форматы для языка Rust. Далее запускаются оригинальные методы библиотеки. Их результат следует преобразовать обратно в C-совместимые структуры, однако в данном случае удается избежать обратной конвертации, поскольку библиотека поддерживает запись напрямую по указателю *mut u8.
|
||
|
||
Кроме того, стоит отметить обязательность аттрибута #[no_mangle] и указания extern "C" для всех таких методов. Без них не удастся провести корректную совместимую с C/C++ компиляцию. Кроме того, они необходимы для следующего этапа подключения библиотеки.
|
||
|
||
После написания кода методов-прослоек нам необходимо подготовить заголовочный файл для библиотеки. Это можно сделать вручную, либо воспользоваться библиотекой cbindgen для автогенерации. В случае с использованием cbindgen, нам понадобится написать сборочный скрипт build.rs и подключить cbindgen в качестве build-dependency.
|
||
|
||
Пример сборочного скрипта, которым можно автосгенерировать заголовочный файл:
|
||
|
||
```
|
||
let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
|
||
|
||
let package_name = env::var("CARGO_PKG_NAME").unwrap();
|
||
let output_file = ("include/".to_owned() + &format!("{}.h", package_name)).to_string();
|
||
|
||
match cbindgen::generate(&crate_dir) {
|
||
Ok(header) => {
|
||
header.write_to_file(&output_file);
|
||
}
|
||
Err(err) => {
|
||
panic!("{}", err)
|
||
}
|
||
}
|
||
```
|
||
|
||
Если возникают пробемы с генерацией заголовков, может потребоваться поработать с конфигурацией cbindgen через файл cbindgen.toml, взяв оригинальный темплейт разработчика cbindgen: [https://github.com/eqrion/cbindgen/blob/master/template.toml](https://github.com/eqrion/cbindgen/blob/master/template.toml).
|
||
|
||
В заключение, стоит отметить проблему, с которой пришлось столкнуться при интеграции BLAKE3:
|
||
C++ MemorySanitizer плохо понимает инициализацию памяти в Rust, поэтому для избежания ложноположительных срабатываний для BLAKE3 был создан альтернативный метод, который более явно, но при этом медленнее, инициализировал память. Он компилируется только для сборки с MemorySanitizer и в релиз не попадает. Вероятно, возможны и более красивые способы решения этой проблемы, но при интеграции BLAKE3 они не были обнаружены.
|