Bun FFI를 사용하는 방법과 사용해야 하는 이유

우리는 무엇을 달성하려고 노력하고 있습니까?

bun에서 실행되는 JavaScript 애플리케이션이 있고 최적화하려는 병목 현상을 식별했다고 가정해 보겠습니다.
보다 성능이 뛰어난 언어로 다시 작성하는 것이 필요한 솔루션일 수 있습니다.

최신 JS 런타임인 Bun은 FFI(외부 함수 인터페이스)를 지원하여 C, C, Rust 및 Zig와 같은 C ABI 노출을 지원하는 다른 언어로 작성된 라이브러리를 호출합니다.

이번 게시물에서는 어떻게 사용할 수 있는지 살펴보고 혜택을 누릴 수 있는지 결론을 내리겠습니다.

라이브러리를 JavaScript에 연결하는 방법

이 예시는 Rust를 사용하고 있습니다. C 바인딩을 사용하여 공유 라이브러리를 만드는 것은 다른 언어에서는 다르게 보이지만 아이디어는 동일합니다.

JS 측에서

Bun은 bun:ffi 모듈을 통해 FFI API를 노출합니다.

진입점은 dlopen 함수입니다. 라이브러리 파일(Linux의 경우 확장자가 .so, macOS의 경우 .dylib, Windows의 경우 .dll인 빌드 출력)에 대한 절대 경로 또는 현재 작업 디렉터리에 대한 상대 경로와 가져오려는 함수의 서명.
더 이상 필요하지 않은 경우 라이브러리를 닫는 데 사용할 수 있는 닫기 메소드와 선택한 기능이 포함된 객체인 기호 속성을 사용하여 객체를 반환합니다.

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();

FFI 경계를 통해 데이터 전달

알다시피 FFI를 통해 bun이 허용하는 지원 유형은 포인터를 포함한 숫자로 제한됩니다.
특히 size_t 또는 usize에 대한 코드가 Bun 버전 1.1.34부터 존재함에도 불구하고 지원되는 유형 목록에서 누락되었습니다.

Bun은 C 문자열보다 더 복잡한 데이터를 전달하는 데 어떤 도움도 제공하지 않습니다. 즉, 포인터를 직접 사용하여 작업해야 합니다.

JavaScript에서 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 



<p>... 그리고 Rust에서 JavaScript로 포인터를 반환하는 방법<br>
</p>

<pre class="brush:php;toolbar:false">{
  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 {
    let buffer: Vec<i32> = vec![0; 10];
    let memory: ManuallyDrop<vec>> = 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
}
</t></vec></i32>

Rust는 JS가 상대방의 데이터 소유권을 갖고 있다는 것을 모르기 때문에 ManuallyDrop을 사용하여 힙에 있는 데이터를 할당 해제하지 마세요 명시적으로 지시해야 합니다. 메모리를 관리하는 다른 언어도 비슷한 작업을 수행해야 합니다.

메모리 관리

보시다시피 JS와 Rust 모두에서 메모리를 할당하는 것이 가능하지만 다른 메모리를 안전하게 관리할 수는 없습니다.

메모리를 어디에 할당하고 어떻게 할당할지 선택하세요.

Rust에서 할당

JS에서 Rust에 메모리 정리를 위임하는 방법에는 3가지가 있으며 모두 장단점이 있습니다.

FinalizationRegistry 사용

JavaScript에서 개체를 추적하여 가비지 수집 중에 정리 콜백을 요청하려면 FinalizationRegistry를 사용하세요.

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);

장점

• 간단해요

단점

• 가비지 수집은 엔진별로 이루어지며 비결정적입니다
• 정리 콜백 호출이 전혀 보장되지 않습니다

toArrayBuffer의 finalizationCallback 매개변수 사용

정리 콜백을 호출하려면 가비지 수집 추적을 bun에 위임하세요.
toArrayBuffer에 4개의 매개변수를 전달할 때 4번째 매개변수는 정리 시 호출되는 C 함수여야 합니다.
단, 5개의 매개변수를 전달할 때 5번째 매개변수는 함수이고 4번째 매개변수는 이를 전달받는 컨텍스트 포인터여야 합니다.

/// 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 





<pre class="brush:php;toolbar:false">{
  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);

장점

• JavaScript에서 로직 위임

단점

• 상용구가 많고 메모리 누수 가능성이 있음
• toArrayBuffer에 대한 유형 주석이 누락되었습니다.
• 가비지 수집은 엔진별로 이루어지며 비결정적입니다
• 정리 콜백 호출이 전혀 보장되지 않습니다

수동으로 메모리 관리

더 이상 필요하지 않은 메모리는 직접 삭제하세요.
다행히 TypeScript에는 이것과 using 키워드에 매우 유용한 일회용 인터페이스가 있습니다.
Python의 with 또는 C#의 using 키워드와 동일합니다.

문서 보기

• TypeScript 5.2 변경 로그
• 사용에 대한 Pull 요청

#[no_mangle]
pub extern "C" fn allocate_buffer() -> Box {
    let buffer: Vec<i32> = vec![0; 10];
    let memory: ManuallyDrop<vec>> = 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
}
</t></vec></i32>

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

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

장점

• 정리 실행 보장
• 메모리 삭제 시기를 제어할 수 있습니다

단점

• 일회용 인터페이스를 위한 상용구 객체
• 수동으로 메모리를 삭제하는 것은 가비지 수집기를 사용하는 것보다 느립니다
• 버퍼의 소유권을 포기하려면 복사본을 만들고 원본을 삭제해야 합니다

JS에서 할당

할당 취소가 자동으로 처리되므로 훨씬 간단하고 안전합니다.

그러나 결정적인 단점이 있습니다.
Rust에서는 JavaScript의 메모리를 관리할 수 없기 때문에 버퍼 용량을 초과하면 할당 해제가 발생하므로 이를 초과할 수 없습니다. 즉, Rust에 전달하기 전에 버퍼 크기를 알아야 합니다.
필요한 버퍼 수를 미리 알지 못하면 할당하기 위해 FFI를 왔다 갔다 하게 되므로 오버헤드가 많이 발생합니다.

/// # 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 = 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);
}
</i32>

{
  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);

문자열에 대한 참고 사항

라이브러리에서 기대하는 출력이 문자열인 경우 일반적으로 JavaScript 엔진은 내부적으로 UTF-16을 사용하므로 문자열이 아닌 u16 벡터를 반환하는 미세 최적화를 고려했을 수 있습니다.

그러나 문자열을 C 문자열로 변환하고 bun의 cstring 유형을 사용하는 것이 약간 더 빠르기 때문에 이는 실수입니다.
다음은 훌륭한 벤치마크 라이브러리 mitata를 사용하여 수행된 벤치마크입니다

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 



<h2>
  
  
  웹어셈블리는 어떻습니까?
</h2>

<p>이제 WebAssembly라는 방에서 코끼리에 대해 이야기할 시간입니다.<br>
C ABI를 처리하는 대신 기존 WASM 바인딩을 선택해야 합니까? </p>

<p>답은 <strong>아마 둘 다 아니다</strong>입니다. </p>
<h2>
  
  
  실제로 그만한 가치가 있습니까?
</h2>

<p>코드베이스에 다른 언어를 도입하려면 DX 측면과 성능 측면에서 가치가 있으려면 단일 병목 현상 이상이 필요합니다. </p>

<p>JS, WASM 및 Rust의 단순 범위 기능에 대한 벤치마크는 다음과 같습니다.<br>
</p>

<pre class="brush:php;toolbar:false">{
  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 {
    let buffer: Vec<i32> = vec![0; 10];
    let memory: ManuallyDrop<vec>> = 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
}
</t></vec></i32>

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

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

네이티브 라이브러리는 WASM을 간신히 이기고 순수 TypeScript 구현에 계속해서 패배합니다.

bun:ffi 모듈에 대한 튜토리얼/탐색은 여기까지입니다. 우리 모두가 좀 더 교육을 받아 이 문제에서 벗어났기를 바랍니다.
댓글로 생각이나 질문을 자유롭게 공유해주세요

위 내용은 Bun FFI를 사용하는 방법과 사용해야 하는 이유의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!