Bagaimana untuk dan Sekiranya anda menggunakan Bun FFI

Apa yang kita cuba capai

Katakan anda mempunyai aplikasi JavaScript yang berjalan dalam sanggul dan anda telah mengenal pasti beberapa halangan yang ingin anda optimumkan.
Menulis semula dalam bahasa yang lebih berprestasi mungkin merupakan penyelesaian yang anda perlukan.

Sebagai masa jalan JS moden, Bun menyokong Antara Muka Fungsi Asing (FFI) untuk memanggil perpustakaan yang ditulis dalam bahasa lain yang menyokong pendedahan C ABI, seperti C, C , Rust dan Zig.

Dalam siaran ini, kami akan membincangkan cara seseorang boleh menggunakannya dan membuat kesimpulan sama ada seseorang itu boleh mendapat manfaat daripadanya.

Cara memautkan pustaka ke JavaScript

Contoh ini menggunakan Rust. Mencipta pustaka kongsi dengan pengikatan C kelihatan berbeza dalam bahasa lain tetapi ideanya tetap sama.

Dari pihak JS

Bun mendedahkan API FFInya melalui modul bun:ffi.

Titik masuk ialah fungsi dlopen. Ia mengambil laluan yang sama ada mutlak atau relatif kepada direktori kerja semasa ke fail perpustakaan (output binaan dengan sambungan .so untuk Linux, .dylib untuk macOS atau .dll untuk Windows) dan objek dengan tandatangan fungsi yang anda ingin import.
Ia mengembalikan objek dengan kaedah tutup yang boleh anda gunakan untuk menutup perpustakaan apabila ia tidak diperlukan lagi dan melambangkan sifat yang merupakan objek yang mengandungi fungsi yang anda pilih.

import {
  dlopen,
  FFIType,
  read,
  suffix,
  toArrayBuffer,
  type Pointer,
} from "bun:ffi";

// Both your script and your library don't typically change their locations
// Use `import.meta.dirname` to make your script independent from the cwd
const DLL_PATH =
  import.meta.dirname + `/../../rust-lib/target/release/library.${suffix}`;

function main() {
  // Deconstruct object to get functions
  // but collect `close` method into object
  // to avoid using `this` in a wrong scope
  const {
    symbols: { do_work },
    ...dll
  } = dlopen(DLL_PATH, {
    do_work: {
      args: [FFIType.ptr, FFIType.ptr, "usize", "usize"],
      returns: FFIType.void,
    },
  });

  /* ... */

  // It is unclear whether it is required or recommended to call `close`
  // an example says `JSCallback` instances specifically need to be closed
  // Note that using `symbols` after calling `close` is undefined behaviour
  dll.close();
}

main();

Melepasi data melalui sempadan FFI

Seperti yang anda perhatikan, jenis yang disokong yang diterima oleh bun melalui FFI adalah terhad kepada nombor, termasuk penunjuk.
Terutama size_t atau usize tiada daripada senarai jenis yang disokong, walaupun kod untuknya wujud pada versi bun 1.1.34.

Bun tidak menawarkan sebarang bantuan dalam menghantar data yang lebih kompleks daripada rentetan C. Ini bermakna anda perlu menggunakan penunjuk sendiri.

Mari lihat cara menghantar penunjuk daripada JavaScript ke Rust ...

{
  reconstruct_slice: {
    args: [FFIType.ptr, "usize"],
    returns: FFIType.void,
  },
}

const array = new BigInt64Array([0, 1, 3]);
// Bun automatically converts `TypedArray`s into pointers
reconstruct_slice(array, array.length);

/// Reconstruct a `slice` that was initialized in JavaScript
unsafe fn reconstruct_slice(
    array_ptr: *const i64,
    length: libc::size_t,
) -> &[i64] {
    // Even though here it's not null, it's good practice to check
    assert!(!array_ptr.is_null());
    // Unaligned pointer can lead to undefined behaviour
    assert!(array_ptr.is_aligned());
    // Check that the array doesn't "wrap around" the address space
    assert!(length < usize::MAX / 4);
    let _: &[i64] = unsafe { slice::from_raw_parts(array_ptr, length) };
}

... dan cara mengembalikan penunjuk daripada Rust kepada JavaScript.

{
  allocate_buffer: {
    args: [],
    returns: FFIType.ptr,
  },
  as_pointer: {
    args: ["usize"],
    returns: FFIType.ptr,
  },
}

// Hardcoding this value for 64-bit systems
const BYTES_IN_PTR = 8;

const box: Pointer = allocate_buffer()!;
const ptr: number = read.ptr(box);
// Reading the value next to `ptr`
const length: number = read.ptr(box, BYTES_IN_PTR);
// Hardcoding `byteOffset` to be 0 because Rust guarantees that
// Buffer holds `i32` values which take 4 bytes
// Note how we need to call a no-op function `as_pointer` because
// `toArrayBuffer` takes a `Pointer` but `read.ptr` returns a `number`
const _buffer = toArrayBuffer(as_pointer(ptr)!, 0, length * 4);

#[no_mangle]
pub extern "C" fn allocate_buffer() -> Box<[usize; 2]> {
    let buffer: Vec<i32> = vec![0; 10];
    let memory: ManuallyDrop<Vec<i32>> = ManuallyDrop::new(buffer);
    let ptr: *const i32 = memory.as_ptr();
    let length: usize = memory.len();
    // Unlike a `Vec`, `Box` is FFI compatible and will not drop
    // its data when crossing the FFI
    // Additionally, a `Box<T>` where `T` is `Sized` will be a thin pointer
    Box::new([ptr as usize, length])
}

#[no_mangle]
pub const extern "C" fn as_pointer(ptr: usize) -> usize {
    ptr
}

Rust tidak tahu JS mengambil pemilikan data di sisi lain, jadi anda perlu memberitahunya secara eksplisit untuk tidak memperuntukkan data pada timbunan menggunakan ManuallyDrop. Bahasa lain yang menguruskan memori perlu melakukan sesuatu yang serupa.

Pengurusan ingatan

Seperti yang kita lihat, anda boleh memperuntukkan memori dalam JS dan Rust, dan kedua-duanya tidak boleh selamat mengurus memori orang lain.

Mari pilih di mana anda harus memperuntukkan ingatan anda dan bagaimana.

Peruntukkan dalam Rust

Terdapat 3 kaedah mewakilkan pembersihan memori kepada Rust daripada JS dan semuanya mempunyai kebaikan dan keburukan mereka.

Gunakan FinalizationRegistry

Gunakan FinalizationRegistry untuk meminta panggilan balik pembersihan semasa pengumpulan sampah dengan menjejaki objek dalam JavaScript.

import {
  dlopen,
  FFIType,
  read,
  suffix,
  toArrayBuffer,
  type Pointer,
} from "bun:ffi";

// Both your script and your library don't typically change their locations
// Use `import.meta.dirname` to make your script independent from the cwd
const DLL_PATH =
  import.meta.dirname + `/../../rust-lib/target/release/library.${suffix}`;

function main() {
  // Deconstruct object to get functions
  // but collect `close` method into object
  // to avoid using `this` in a wrong scope
  const {
    symbols: { do_work },
    ...dll
  } = dlopen(DLL_PATH, {
    do_work: {
      args: [FFIType.ptr, FFIType.ptr, "usize", "usize"],
      returns: FFIType.void,
    },
  });

  /* ... */

  // It is unclear whether it is required or recommended to call `close`
  // an example says `JSCallback` instances specifically need to be closed
  // Note that using `symbols` after calling `close` is undefined behaviour
  dll.close();
}

main();

{
  reconstruct_slice: {
    args: [FFIType.ptr, "usize"],
    returns: FFIType.void,
  },
}

const array = new BigInt64Array([0, 1, 3]);
// Bun automatically converts `TypedArray`s into pointers
reconstruct_slice(array, array.length);

Kebaikan

• Mudah sahaja

Kontra

• Pengumpulan sampah adalah khusus enjin dan bukan penentu
• Panggil balik pembersihan tidak dijamin akan dipanggil sama sekali

Gunakan toArrayBuffer's finalizationCallback parameter

Tugaskan penjejakan kutipan sampah kepada sanggul untuk memanggil panggilan balik pembersihan.
Apabila menghantar 4 parameter kepada ArrayBuffer, yang ke-4 mestilah fungsi C untuk dipanggil semasa pembersihan.
Walau bagaimanapun, apabila melepasi 5 parameter, parameter ke-5 ialah fungsi dan parameter ke-4 mestilah penuding konteks yang melepasinya.

/// Reconstruct a `slice` that was initialized in JavaScript
unsafe fn reconstruct_slice(
    array_ptr: *const i64,
    length: libc::size_t,
) -> &[i64] {
    // Even though here it's not null, it's good practice to check
    assert!(!array_ptr.is_null());
    // Unaligned pointer can lead to undefined behaviour
    assert!(array_ptr.is_aligned());
    // Check that the array doesn't "wrap around" the address space
    assert!(length < usize::MAX / 4);
    let _: &[i64] = unsafe { slice::from_raw_parts(array_ptr, length) };
}

{
  allocate_buffer: {
    args: [],
    returns: FFIType.ptr,
  },
  as_pointer: {
    args: ["usize"],
    returns: FFIType.ptr,
  },
}

// Hardcoding this value for 64-bit systems
const BYTES_IN_PTR = 8;

const box: Pointer = allocate_buffer()!;
const ptr: number = read.ptr(box);
// Reading the value next to `ptr`
const length: number = read.ptr(box, BYTES_IN_PTR);
// Hardcoding `byteOffset` to be 0 because Rust guarantees that
// Buffer holds `i32` values which take 4 bytes
// Note how we need to call a no-op function `as_pointer` because
// `toArrayBuffer` takes a `Pointer` but `read.ptr` returns a `number`
const _buffer = toArrayBuffer(as_pointer(ptr)!, 0, length * 4);

Kebaikan

• Mewakilkan logik daripada JavaScript

Kontra

• Banyak boilerplate dan peluang untuk membocorkan ingatan
• Tiada anotasi jenis untuk toArrayBuffer
• Pengumpulan sampah adalah khusus enjin dan bukan penentu
• Panggil balik pembersihan tidak dijamin akan dipanggil sama sekali

Urus memori secara manual

Hanya tinggalkan ingatan itu sendiri selepas anda tidak memerlukannya lagi.
Nasib baik TypeScript mempunyai antara muka Pakai Pakai yang sangat membantu untuk ini dan menggunakan kata kunci.
Ia setara dengan Python dengan atau C# menggunakan kata kunci.

Lihat dokumen untuknya

• Log perubahan TypeScript 5.2
• Tarik permintaan untuk menggunakan

#[no_mangle]
pub extern "C" fn allocate_buffer() -> Box<[usize; 2]> {
    let buffer: Vec<i32> = vec![0; 10];
    let memory: ManuallyDrop<Vec<i32>> = ManuallyDrop::new(buffer);
    let ptr: *const i32 = memory.as_ptr();
    let length: usize = memory.len();
    // Unlike a `Vec`, `Box` is FFI compatible and will not drop
    // its data when crossing the FFI
    // Additionally, a `Box<T>` where `T` is `Sized` will be a thin pointer
    Box::new([ptr as usize, length])
}

#[no_mangle]
pub const extern "C" fn as_pointer(ptr: usize) -> usize {
    ptr
}

{
  drop_buffer: {
    args: [FFIType.ptr],
    returns: FFIType.void,
  },
}

const registry = new FinalizationRegistry((box: Pointer): void => {
  drop_buffer(box);
});
registry.register(buffer, box);

Kebaikan

• Pembersihan dijamin berjalan
• Anda mempunyai kawalan apabila anda mahu kehilangan ingatan

Kontra

• Objek boilerplate untuk antara muka pakai buang
• Menggugurkan memori secara manual adalah lebih perlahan daripada menggunakan pemungut sampah
• Jika anda ingin memberikan hak milik penimbal, anda perlu membuat salinan dan menggugurkan yang asal

Peruntukkan dalam JS

Ini adalah lebih mudah dan lebih selamat kerana penetapan lokasi dikendalikan untuk anda.

Walau bagaimanapun, terdapat kelemahan yang ketara.
Memandangkan anda tidak boleh mengurus memori JavaScript dalam Rust, anda tidak boleh mengatasi kapasiti penimbal kerana ini akan menyebabkan deallocation. Ini bermakna anda perlu mengetahui saiz penimbal sebelum menghantarnya kepada Rust.
Tidak mengetahui berapa banyak penimbal yang anda perlukan terlebih dahulu juga akan menanggung banyak overhed kerana anda akan berulang alik melalui FFI hanya untuk memperuntukkan.

/// # Safety
///
/// This call assumes neither the box nor the buffer have been mutated in JS
#[no_mangle]
pub unsafe extern "C" fn drop_buffer(raw: *mut [usize; 2]) {
    let box_: Box<[usize; 2]> = unsafe { Box::from_raw(raw) };
    let ptr: *mut i32 = box_[0] as *mut i32;
    let length: usize = box_[1];
    let buffer: Vec<i32> = unsafe { Vec::from_raw_parts(ptr, length, length) };
    drop(buffer);
}

{
  box_value: {
    args: ["usize"],
    returns: FFIType.ptr,
  },
  drop_box: {
    args: [FFIType.ptr],
    returns: FFIType.void,
  },
  drop_buffer: {
    args: [FFIType.ptr, FFIType.ptr],
    returns: FFIType.void,
  },
}

// Bun expects the context to specifically be a pointer
const finalizationCtx: Pointer = box_value(length)!;

// Note that despite the presence of these extra parameters in the docs,
// they're absent from `@types/bun`
//@ts-expect-error see above
const buffer = toArrayBuffer(
  as_pointer(ptr)!,
  0,
  length * 4,
  //@ts-expect-error see above
  finalizationCtx,
  drop_buffer,
);
// Don't leak the box used to pass buffer through FFI
drop_box(box);

Catatan sampingan pada rentetan

Jika output yang anda jangkakan daripada pustaka ialah rentetan, anda mungkin telah mempertimbangkan pengoptimuman mikro untuk mengembalikan vektor u16 dan bukannya rentetan kerana biasanya enjin JavaScript menggunakan UTF-16 di bawah hud.

Walau bagaimanapun, itu adalah satu kesilapan kerana menukar rentetan anda kepada rentetan C dan menggunakan jenis crentetan bun akan menjadi lebih pantas.
Berikut ialah penanda aras yang dilakukan menggunakan mitata perpustakaan penanda aras yang bagus

import {
  dlopen,
  FFIType,
  read,
  suffix,
  toArrayBuffer,
  type Pointer,
} from "bun:ffi";

// Both your script and your library don't typically change their locations
// Use `import.meta.dirname` to make your script independent from the cwd
const DLL_PATH =
  import.meta.dirname + `/../../rust-lib/target/release/library.${suffix}`;

function main() {
  // Deconstruct object to get functions
  // but collect `close` method into object
  // to avoid using `this` in a wrong scope
  const {
    symbols: { do_work },
    ...dll
  } = dlopen(DLL_PATH, {
    do_work: {
      args: [FFIType.ptr, FFIType.ptr, "usize", "usize"],
      returns: FFIType.void,
    },
  });

  /* ... */

  // It is unclear whether it is required or recommended to call `close`
  // an example says `JSCallback` instances specifically need to be closed
  // Note that using `symbols` after calling `close` is undefined behaviour
  dll.close();
}

main();

{
  reconstruct_slice: {
    args: [FFIType.ptr, "usize"],
    returns: FFIType.void,
  },
}

const array = new BigInt64Array([0, 1, 3]);
// Bun automatically converts `TypedArray`s into pointers
reconstruct_slice(array, array.length);

/// Reconstruct a `slice` that was initialized in JavaScript
unsafe fn reconstruct_slice(
    array_ptr: *const i64,
    length: libc::size_t,
) -> &[i64] {
    // Even though here it's not null, it's good practice to check
    assert!(!array_ptr.is_null());
    // Unaligned pointer can lead to undefined behaviour
    assert!(array_ptr.is_aligned());
    // Check that the array doesn't "wrap around" the address space
    assert!(length < usize::MAX / 4);
    let _: &[i64] = unsafe { slice::from_raw_parts(array_ptr, length) };
}

Bagaimana pula dengan WebAssembly?

Sudah tiba masanya untuk menangani gajah di dalam bilik iaitu WebAssembly.
Sekiranya anda memilih pengikatan WASM sedia ada yang bagus daripada berurusan dengan C ABI?

Jawapannya mungkin juga tidak.

Adakah ia sebenarnya berbaloi?

Memperkenalkan bahasa lain ke pangkalan kod anda memerlukan lebih daripada satu kesesakan untuk berbaloi dari segi DX dan prestasi.

Berikut ialah penanda aras untuk fungsi julat ringkas dalam JS, WASM dan Rust.

{
  allocate_buffer: {
    args: [],
    returns: FFIType.ptr,
  },
  as_pointer: {
    args: ["usize"],
    returns: FFIType.ptr,
  },
}

// Hardcoding this value for 64-bit systems
const BYTES_IN_PTR = 8;

const box: Pointer = allocate_buffer()!;
const ptr: number = read.ptr(box);
// Reading the value next to `ptr`
const length: number = read.ptr(box, BYTES_IN_PTR);
// Hardcoding `byteOffset` to be 0 because Rust guarantees that
// Buffer holds `i32` values which take 4 bytes
// Note how we need to call a no-op function `as_pointer` because
// `toArrayBuffer` takes a `Pointer` but `read.ptr` returns a `number`
const _buffer = toArrayBuffer(as_pointer(ptr)!, 0, length * 4);

#[no_mangle]
pub extern "C" fn allocate_buffer() -> Box<[usize; 2]> {
    let buffer: Vec<i32> = vec![0; 10];
    let memory: ManuallyDrop<Vec<i32>> = ManuallyDrop::new(buffer);
    let ptr: *const i32 = memory.as_ptr();
    let length: usize = memory.len();
    // Unlike a `Vec`, `Box` is FFI compatible and will not drop
    // its data when crossing the FFI
    // Additionally, a `Box<T>` where `T` is `Sized` will be a thin pointer
    Box::new([ptr as usize, length])
}

#[no_mangle]
pub const extern "C" fn as_pointer(ptr: usize) -> usize {
    ptr
}

{
  drop_buffer: {
    args: [FFIType.ptr],
    returns: FFIType.void,
  },
}

const registry = new FinalizationRegistry((box: Pointer): void => {
  drop_buffer(box);
});
registry.register(buffer, box);

Pustaka asli hampir tidak mengalahkan WASM dan secara konsisten kalah kepada pelaksanaan TypeScript tulen.

Dan itu sahaja untuk tutorial ini untuk/penerokaan modul bun:ffi. Semoga kita semua telah menjauhi perkara ini dengan lebih berpendidikan.
Jangan ragu untuk berkongsi pemikiran dan soalan dalam komen

Atas ialah kandungan terperinci Bagaimana untuk dan Sekiranya anda menggunakan Bun FFI. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!