XFFI kullanım rehberi

bun-xffi, exoproc-utils dışındaki Exoproc paketlerinin tip, bellek ve çağrı temelidir. Adındaki x, cross-process çalışmayı; ffi, C ABI ile tür/çağrı katmanını ifade eder. Aynı struct tanımı hem yerel bellekte hem de bir accessor üzerinden uzak bellekte kullanılabilir.

Bu, yalnızca uzaktaki bir adrese read()/write() göndermek değildir: CFunction, pointer, struct yerleşimi ve IMemoryAccessor yüzü, üst paketlerin yerel/uzak veya NThread üzerinden yürütülen işlemleri aynı modelle kurmasını sağlar. bun-winapi, bun-nthread, exoproc-accessors ve hook paketleri bu zemini kullanır.

Struct tanımlama

import { struct } from 'bun-xffi';

const Vector3 = struct({ x: 'f32', y: 'f32', z: 'f32' });
const vector = Vector3.allocSync();

vector.x = 1;
vector.y = 2.5;
vector.z = -5;
console.log(vector.x, vector.y, vector.z);

Struct derleyicisi alan offset'lerini, hizalamayı ve padding'i hesaplar. Elle DataView offset'i yazmak yerine layout'un tek bir yerde tanımlanması, nested struct'larda özellikle önemlidir.

Uzak accessor ile aynı tanım

const player = new Player(entityAddress, memory);
await player.set('health', 999);
const health = await player.health;

Yerel ve uzak nesne arasındaki fark erişim zamanlamasıdır: uzak accessor işlemleri async olabilir. Bu nedenle bir sayfadaki API örneği, hangi accessor ile çalıştığını açıkça belirtmelidir.

Runtime C ve native symbol'ler

cjitopen, TinyCC ile çalışma zamanında C kaynak kodunu makine koduna dönüştürür. cimport, sistem DLL'lerindeki export'ları doğrudan C ABI tanımıyla çağrılabilir hale getirir. Her iki durumda da kaynak kodu değil, son çağrı imzası güvenlik sınırıdır: yanlış tür veya pointer hedef süreci çökertir.

import { cjitopen, CType } from 'bun-xffi';

const lib = cjitopen({
  multiply: {
    args: [CType.i32, CType.i32],
    returns: CType.i32,
    source: 'return arg0 * arg1;',
  },
});

console.log(lib.symbols.multiply(6, 7));
lib.close();