В данном руководстве в качестве примера мы будем использовать
snappy, библиотеку для сжатия/распаковки
данных. Мы реализуем Rust-интерфейс к этой библиотеке через вызов внешних
функций. Rust в настоящее время не в состоянии делать вызовы напрямую в
библиотеки C++, но snappy включает в себя интерфейс C (документирован в
snappy-c.h).
Ниже приведен минимальный пример вызова внешней функции, который будет скомпилирован при условии, что библиотека snappy установлена:
#![feature(libc)] extern crate libc; use libc::size_t; #[link(name = "snappy")] extern { fn snappy_max_compressed_length(source_length: size_t) -> size_t; } fn main() { let x = unsafe { snappy_max_compressed_length(100) }; println!("максимальный размер сжатого буфера длиной 100 байт: {}", x); }extern crate libc; use libc::size_t; #[link(name = "snappy")] extern { fn snappy_max_compressed_length(source_length: size_t) -> size_t; } fn main() { let x = unsafe { snappy_max_compressed_length(100) }; println!("максимальный размер сжатого буфера длиной 100 байт: {}", x); }
Блок extern содержит список сигнатур функций из внешней библиотеки, в данном
случае для C ABI (application binary interface; двоичный интерфейс приложений)
данной платформы. Чтобы указать, что программу нужно компоновать с библиотекой
snappy, используется атрибут #[link(...)]. Благодаря этому, символы будут
успешно разрешены.
Предполагается, что внешние функции могут быть небезопасными, поэтому их вызовы
должны быть обёрнуты в блок unsafe {} как обещание компилятору, что все внутри
этого блока в действительности безопасно. Библиотеки C часто предоставляют
интерфейсы, которые не являются потоко-безопасными. И почти любая функция,
которая принимает в качестве аргумента указатель, не может принимать любое
входное значений, поскольку указатель может быть висячим; сырые указатели
выходят за пределы безопасной модели памяти в Rust.
При объявлении типов аргументов для внешней функции, компилятор Rust не может проверить, является ли данное объявление корректным. Поэтому важно правильно указать тип привязываемой функции — иначе ошибка обнаружится только во время исполнения.
Блок extern может быть распространён на весь API snappy:
extern crate libc; use libc::{c_int, size_t}; #[link(name = "snappy")] extern { fn snappy_compress(input: *const u8, input_length: size_t, compressed: *mut u8, compressed_length: *mut size_t) -> c_int; fn snappy_uncompress(compressed: *const u8, compressed_length: size_t, uncompressed: *mut u8, uncompressed_length: *mut size_t) -> c_int; fn snappy_max_compressed_length(source_length: size_t) -> size_t; fn snappy_uncompressed_length(compressed: *const u8, compressed_length: size_t, result: *mut size_t) -> c_int; fn snappy_validate_compressed_buffer(compressed: *const u8, compressed_length: size_t) -> c_int; }
Сырой C API (application programming interface; интерфейс программирования приложений) необходимо обернуть, чтобы обеспечить безопасность памяти. Тогда мы сможем использовать концепции более высокого уровня, такие как векторы. Библиотека может выборочно открывать только безопасный, высокоуровневый интерфейс и скрывать небезопасные внутренние детали.
Оборачивание функций, которые принимают в качестве входных параметров буферы,
включает в себя использование модуля slice::raw для управления векторами Rust
как указателями на память. Векторы Rust представляют собой гарантированно
непрерывный блок памяти. Длина — это количество элементов, которое в настоящее
время содержится в векторе, а ёмкость — общее количество выделенной памяти в
элементах. Длина меньше или равна ёмкости.
pub fn validate_compressed_buffer(src: &[u8]) -> bool { unsafe { snappy_validate_compressed_buffer(src.as_ptr(), src.len() as size_t) == 0 } }
Обёртка validate_compressed_buffer использует блок unsafe, но это
гарантирует, что её вызов будет безопасен для всех входных данных, поскольку
модификатор unsafe отсутствует в сигнатуре функции. Т.е. небезопасность скрыта
внутри функции и не видна вызывающему.
Функции snappy_compress и snappy_uncompress являются более сложными, так как
должен быть выделен буфер для хранения выходных данных.
Функция snappy_max_compressed_length может быть использована для выделения
вектора максимальной ёмкости, требуемой для хранения сжатых выходных данных.
Затем этот вектор может быть передан в функцию snappy_compress в качестве
выходного параметра. Ещё один параметр передается, чтобы получить настоящую
длину после сжатия и установить соответствующую длину вектора.
pub fn compress(src: &[u8]) -> Vec<u8> { unsafe { let srclen = src.len() as size_t; let psrc = src.as_ptr(); let mut dstlen = snappy_max_compressed_length(srclen); let mut dst = Vec::with_capacity(dstlen as usize); let pdst = dst.as_mut_ptr(); snappy_compress(psrc, srclen, pdst, &mut dstlen); dst.set_len(dstlen as usize); dst } }
Распаковка аналогична, потому что snappy хранит размер несжатых данных как часть
формата сжатия, и snappy_uncompressed_length будет возвращать точный размер
необходимого буфера.
pub fn uncompress(src: &[u8]) -> Option<Vec<u8>> { unsafe { let srclen = src.len() as size_t; let psrc = src.as_ptr(); let mut dstlen: size_t = 0; snappy_uncompressed_length(psrc, srclen, &mut dstlen); let mut dst = Vec::with_capacity(dstlen as usize); let pdst = dst.as_mut_ptr(); if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 { dst.set_len(dstlen as usize); Some(dst) } else { None // SNAPPY_INVALID_INPUT } } }
Для справки, примеры, используемые здесь, также доступны в библиотеке на GitHub.
Внешние библиотеки часто передают владение ресурсами в вызывающий код. Когда это происходит, мы должны использовать деструкторы Rust, чтобы обеспечить безопасность и гарантировать освобождение этих ресурсов (особенно в случае паники).
Чтобы получить более подробную информацию о деструкторах, смотрите типаж Drop.
Некоторые внешние библиотеки требуют использование обратных вызовов для передачи
вызывающей стороне отчета о своем текущем состоянии или промежуточных данных. Во
внешнюю библиотеку можно передавать функции, которые были определены в Rust. При
создании функции обратного вызова, которую можно вызывать из C кода, необходимо
указать для нее спецификатор extern, за котороым следует подходящее соглашение
о вызове.
Затем функция обратного вызова может быть передана в библиотеку C через регистрационный вызов, и уже затем может быть вызвана оттуда.
Простой пример:
Код на Rust:
extern fn callback(a: i32) { println!("Меня вызывают из C со значением {0}", a); } #[link(name = "extlib")] extern { fn register_callback(cb: extern fn(i32)) -> i32; fn trigger_callback(); } fn main() { unsafe { register_callback(callback); trigger_callback(); // Активация функции обратного вызова } }extern fn callback(a: i32) { println!("Меня вызывают из C со значением {0}", a); } #[link(name = "extlib")] extern { fn register_callback(cb: extern fn(i32)) -> i32; fn trigger_callback(); } fn main() { unsafe { register_callback(callback); trigger_callback(); // Активация функции обратного вызова } }
Код на C:
typedef void (*rust_callback)(int32_t);
rust_callback cb;
int32_t register_callback(rust_callback callback) {
cb = callback;
return 1;
}
void trigger_callback() {
cb(7); // Вызовет callback(7) в Rust
}
В этом примере функция main() в Rust вызовет функцию trigger_callback() в C,
которая, в свою очередь, выполнит обратный вызов функции callback() в Rust.
Предыдущий пример показал, как глобальная функция может быть вызвана из C кода. Однако зачастую желательно, чтобы обратный вызов был адресован конкретному объекту в Rust. Это может быть объект, который представляет собой обертку для соответствующего объекта C.
Такое поведение может быть достигнуто путем передачи небезопасного указателя на объект в библиотеку C. После чего библиотека C сможет передавать указатель на объект Rust при обратном вызове. Это позволит получить небезопасный доступ к объекту Rust, на которой сослались в обратном вызове.
Код на Rust:
#[repr(C)] struct RustObject { a: i32, // другие поля } extern "C" fn callback(target: *mut RustObject, a: i32) { println!("Меня вызывают из C со значением {0}", a); unsafe { // Меняем значение в RustObject на значение, полученное через функцию обратного вызова (*target).a = a; } } #[link(name = "extlib")] extern { fn register_callback(target: *mut RustObject, cb: extern fn(*mut RustObject, i32)) -> i32; fn trigger_callback(); } fn main() { // Создаём объект, на который будем ссылаться в функции обратного вызова let mut rust_object = Box::new(RustObject { a: 5 }); unsafe { register_callback(&mut *rust_object, callback); trigger_callback(); } }#[repr(C)] struct RustObject { a: i32, // другие поля } extern "C" fn callback(target: *mut RustObject, a: i32) { println!("Меня вызывают из C со значением {0}", a); unsafe { // Меняем значение в RustObject на значение, полученное через функцию обратного вызова (*target).a = a; } } #[link(name = "extlib")] extern { fn register_callback(target: *mut RustObject, cb: extern fn(*mut RustObject, i32)) -> i32; fn trigger_callback(); } fn main() { // Создаём объект, на который будем ссылаться в функции обратного вызова let mut rust_object = Box::new(RustObject { a: 5 }); unsafe { register_callback(&mut *rust_object, callback); trigger_callback(); } }
Код на C:
typedef void (*rust_callback)(void*, int32_t);
void* cb_target;
rust_callback cb;
int32_t register_callback(void* callback_target, rust_callback callback) {
cb_target = callback_target;
cb = callback;
return 1;
}
void trigger_callback() {
cb(cb_target, 7); // Вызовет callback(&rustObject, 7) в Rust
}
В приведённых примерах обратные вызовы выполняются как непосредственная реакция на вызов функции внешней библиотеки на C. Для выполнения обратного вызова поток исполнения переключался из Rust в C, а затем снова в Rust, но, в конце концов, обратный вызов выполнялся в том же потоке, из которого была вызвана функция, инициировавшая обратный вызов.
Более сложная ситуация — это когда внешняя библиотека порождает свои собственные
потоки и осуществляет обратные вызовы из них. В этих случаях доступ к структурам
данных Rust из обратных вызовов особенно опасен, и поэтому нужно использовать
соответствующие механизмы синхронизации. Помимо классических механизмов
синхронизации, таких как мьютексы, в Rust есть еще одна возможность:
использовать каналы (std::sync::mpsc::channel), чтобы направить данные из
потока C, который выполнял обратный вызов, в поток Rust.
Если асинхронный обратный вызов адресован конкретному объекту в адресном пространстве Rust, то необходимо, чтобы обратные вызовы не выполнялись библиотекой C после уничтожения этого объекта Rust. Для этого следует, во-первых, проектировать библиотеку таким образом, чтобы отмена регистрации обратного вызова гарантировала, что он больше не будет выполняться. Во-вторых, нужно отменить регистрацию обратного вызова в деструкторе объекта Rust, которому адресован обратный вызов.
Атрибут link для блоков extern предоставляет rustc основные инструкции
относительно того, как он должен компоновать нативные библиотеки. На данный
момент есть две общепринятых формы записи атрибута link:
#[link(name = "foo")]#[link(name = "foo", kind = "bar")]В обоих этих случаях foo — это имя нативной библиотеки, с которой мы
компонуемся. Во втором случае bar — это тип нативной библиотеки, с которой
происходит компоновка. В настоящее время rustc известны три типа нативных
библиотек:
#[link(name = "readline")]#[link(name = "my_build_dependency", kind = "static")]#[link(name = "CoreFoundation", kind = "framework")]Обратите внимание, что фреймворки доступны только для OSX.
Различные значения kind нужны, чтобы определить, как компоновать нативную
библиотеку. С точки зрения компоновки, компилятор Rust создает две разновидности
артефактов: промежуточный (rlib/статическая библиотека) и конечный (динамическая
библиотека/исполняемый файл). (Прим. переводчика: rlib — это формат статической
библиотеки с метаданными в формате Rust) Зависимости от нативных динамических
библиотек и фреймворков распространяются дальше, пока не дойдут до конечного
артефакта, а от статических библиотек — нет.
Вот несколько примеров того, как эта модель может быть использована:
Нативная зависимость при сборке. Иногда написанный на Rust код необходимо
состыковать с некоторым кодом на C/C++, но распространение C/C++ кода в формате
библиотеки вызывает дополнительные трудности. В этом случае, код будут
упакован в libfoo.a, а затем контейнер Rust должен будет объявить
зависимость с помощью #[link(name = "foo", kind = "static")].
Независимо от типа результата (промежуточный или конечный) контейнера, нативная статическая библиотека будет включена в него на выходе, поэтому нет необходимости в распространении этой нативной статической библиотеки отдельно.
Обычная динамическая зависимость. Общие системные библиотеки (такие, как
readline) доступны на большом количестве систем, и статическую копию этих
библиотек часто сложно найти. Когда такая зависимость включена в контейнер
Rust, промежуточные артефакты (например, rlib'ы) не будут компоноваться с
библиотекой, но когда rlib включается в состав конечного артефакта (например,
исполняемый файл), нативная библиотека будет прикомпонована.
На OSX, фреймворки ведут себя так же, как и динамические библиотеки.
Некоторые операции, такие как разыменование небезопасных указателей или вызов функций, которые были отмечены как небезопасные, разрешено использовать только внутри небезопасных блоков. Небезопасные блоки изолируют опасные ситуации и дают гарантии компилятору, что опасности не вытекут за пределы блока.
Небезопасные функции же, наоборот, показывают свою опасность всем. Небезопасная функция записывается в виде:
fn main() { unsafe fn kaboom(ptr: *const i32) -> i32 { *ptr } }unsafe fn kaboom(ptr: *const i32) -> i32 { *ptr }
Эта функция может быть вызвана только из блока unsafe или из другой unsafe
функции.
Внешние API довольно часто экспортируют глобальные переменные, которые могут
быть использованы, например, для отслеживания глобального состояния. Для того,
чтобы получить доступ к этим переменным, нужно объявить их в блоке extern,
используя ключевое слово static:
extern crate libc; #[link(name = "readline")] extern { static rl_readline_version: libc::c_int; } fn main() { println!("You have readline version {} installed.", rl_readline_version as i32); }
Кроме того, возможно, вам потребуется изменить глобальное состояние,
предоставленное внешним интерфейсом. Для этого при объявлении статических
переменных может быть добавлен модификатор mut, чтобы была возможность
изменять их.
extern crate libc; use std::ffi::CString; use std::ptr; #[link(name = "readline")] extern { static mut rl_prompt: *const libc::c_char; } fn main() { let prompt = CString::new("[my-awesome-shell] $").unwrap(); unsafe { rl_prompt = prompt.as_ptr(); println!("{:?}", rl_prompt); rl_prompt = ptr::null(); } }
Обратите внимание, что любое взаимодействие с static mut небезопасно — как
чтение, так и запись. Работа с изменяемым глобальным состоянием требует
значительно большей осторожности.
Большинство внешнего кода предоставляет C ABI. И Rust при вызове внешних функций по умолчанию использует соглашение о вызове C для данной платформы. Но некоторые внешние функции, в первую очередь Windows API, используют другое соглашение о вызове. Rust обеспечивает способ указать компилятору, какое именно соглашение использовать:
#![feature(libc)] extern crate libc; #[cfg(all(target_os = "win32", target_arch = "x86"))] #[link(name = "kernel32")] #[allow(non_snake_case)] extern "stdcall" { fn SetEnvironmentVariableA(n: *const u8, v: *const u8) -> libc::c_int; } fn main() { }extern crate libc; #[cfg(all(target_os = "win32", target_arch = "x86"))] #[link(name = "kernel32")] #[allow(non_snake_case)] extern "stdcall" { fn SetEnvironmentVariableA(n: *const u8, v: *const u8) -> libc::c_int; }
Это указание относится ко всему блоку extern. Вот список поддерживаемых
ограничений для ABI:
stdcallaapcscdeclfastcallRustrust-intrinsicsystemCwin64Большинство ABI в этом списке не требуют пояснений, но ABI system может
показаться немного странным. Он выбирает такое ABI, которое подходит для
взаимодействия с нативными библиотеками данной платформы. Например, на платформе
win32 с архитектурой x86, это означает, что будет использован ABI stdcall.
Однако, на windows x86_64 используется соглашение о вызове C, поэтому в этом
случае будет использован C ABI. Это означает, что в нашем предыдущем примере
мы могли бы использовать extern "system" { ... }, чтобы определить блок для
всех windows систем, а не только для x86.
Rust гарантирует, что размещение полей struct совместимо с представлением в C
только в том случае, если к ней применяется атрибут #[repr(C)]. Атрибут
#[repr(C, packed)] может быть использован для размещения полей структуры без
выравнивания. Атрибут #[repr(C)] также может быть применен и к перечислениям.
Владеющие упаковки в Rust (Box<T>) используют указатели, не допускающие
нулевое значение (non-nullable), как дескрипторы содержащихся в них объектов.
Тем не менее, эти дескрипторы не должны создаваться вручную, так как они
управляются внутренними средствами выделения памяти. Ссылки можно без риска
считать ненулевыми указателями непосредствено на тип. Однако нарушение правил
проверки заимствования или изменяемости может быть небезопасным. Но компилятор
не может сделать так много предположений о сырых указателях. Например, он не
полагается на настоящую неизменяемость данных под неизменяемым сырым указателем.
Поэтому используйте сырые указатели (*), если вам необходимо намеренно
нарушить правила (но так, что при этом всё работает). Это нужно, чтобы
компилятор «случайно» не предположил относительно ссылок чего-то, что мы
собираемся нарушать (возможно, нам нужны несколько указателей с правом
изменения, что не допускается обычными ссылками).
Векторы и строки совместно используют одну и ту же базовую cхему размещения
памяти и утилиты, доступные в модулях vec и str, для работы с C API. Однако,
строки не завершаются нулевым байтом, \0. Если вам нужна строка, завершающаяся
нулевым байтом, для совместимости с C, вы должны использовать тип CString из
модуля std::ffi.
Стандартная библиотека включает в себя псевдонимы типов и определения функций
для стандартной библиотеки C в модуле libc, и Rust компонует libc и libm
по умолчанию.
Некоторые типы по определению не могут быть null. Это ссылки (&T, &mut T),
упаковки (Box<T>), указатели на функции (extern "abi" fn()). При
взаимодействии же с С часто используются указатели, которые могут быть null.
Как особый случай — обобщенный enum, который содержит ровно два варианта, один
из которых не содержит данных, а другой содержит одно поле. Такое использование
перечисления имеет право на «оптимизацию указателя, допускающего нулевое
значение». Когда создан экземпляр такого перечисления с одним из не-обнуляемых
типов, то он представляет собой ненулевой указатель для варианта, содержащего
данные, и нулевой — для варианта без данных. Таким образом, Option<extern "C" fn(c_int) -> c_int> — это представление указателя на функцию, допускающего
нулевое значение, и совместимого с C ABI.
Вы можете скомпилировать код на Rust таким образом, чтобы он мог быть вызван из кода на C. Это довольно легко, но требует нескольких вещей:
#[no_mangle] pub extern fn hello_rust() -> *const u8 { "Hello, world!\0".as_ptr() } fn main() {}#[no_mangle] pub extern fn hello_rust() -> *const u8 { "Hello, world!\0".as_ptr() }
extern указывает, что эта функцию придерживается соглашения о вызове C, как
описано выше в разделе
«Соглашение о вызове внешних функций».
Атрибут no_mangle выключает изменение имён, применяемое в Rust, чтобы было
легче компоноваться с этим кодом.