FFI

Интерфейс для вызова внешних функций (Foreign Function Interface). Вызывайте функции из разделяемых библиотек (например, C/C++) напрямую из Deno.

Полезно для интеграции с существующим машинным кодом или доступа к низкоуровневым функциям системы.

Например: Deno.dlopen

класс Deno.UnsafeCallback

Небезопасный указатель на функцию для передачи функций JavaScript в качестве указателей на функции C при вызове внешних функций.

Указатель на функцию остается действительным до вызова метода close().

Все UnsafeCallback всегда потокобезопасны: их можно вызывать из внешних потоков без сбоев. Однако по умолчанию они не пробуждают цикл событий Deno.

Если обратный вызов должен вызываться из внешних потоков, используйте статический конструктор threadSafe() или явно вызовите ref(), чтобы обратный вызов пробуждал цикл событий Deno при вызове из внешних потоков. Это также не позволяет процессу Deno завершиться, пока обратный вызов существует и не снята его ссылка.

Затем используйте deref(), чтобы разрешить завершение процесса Deno. Вызов deref() для обратного вызова с установленной ссылкой не мешает ему пробуждать цикл событий Deno при вызове из внешних потоков.

Конструкторы

UnsafeCallback(

definition: Definition,

callback: UnsafeCallbackFunction<Definition["parameters"], Definition["result"]>,
)

новый

Параметры типа

Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition

Свойства

callback: UnsafeCallbackFunction<Definition["parameters"], Definition["result"]>

только для чтения

Функция обратного вызова.

definition: Definition

только для чтения

Определение небезопасного обратного вызова.

pointer: PointerObject<Definition>

только для чтения

Указатель на небезопасный обратный вызов.

Методы

close(): void

Удаляет указатель на функцию C, связанный с этим экземпляром.

Продолжение использования экземпляра или указателя на функцию C после закрытия UnsafeCallback приведет к ошибкам и сбоям.

Вызов этого метода обнуляет счетчик ссылок обратного вызова, прекращает пробуждение им цикла событий Deno при вызове из внешних потоков и больше не препятствует завершению процесса Deno.

ref(): number

Увеличивает счетчик ссылок обратного вызова и возвращает новое значение счетчика.

После вызова ref() обратный вызов всегда пробуждает цикл событий Deno при вызове из внешних потоков.

Если счетчик ссылок обратного вызова не равен нулю, он препятствует завершению процесса Deno.

unref(): number

Уменьшает счетчик ссылок обратного вызова и возвращает новое значение счетчика.

Вызов unref() не мешает обратному вызову пробуждать цикл событий Deno при вызове из внешних потоков.

Если счетчик ссылок обратного вызова равен нулю, он больше не препятствует завершению процесса Deno.

Статические методы

threadSafe<Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition>(

definition: Definition,

callback: UnsafeCallbackFunction<Definition["parameters"], Definition["result"]>,
): UnsafeCallback<Definition>

Создает UnsafeCallback и один раз вызывает ref(), чтобы тот мог пробуждать цикл событий Deno при вызове из внешних потоков.

Это также не позволяет процессу Deno завершиться, пока обратный вызов существует и не снята его ссылка.

класс Deno.UnsafeFnPointer

Небезопасный указатель на функцию для вызова функций, отсутствующих среди символов.

Конструкторы

UnsafeFnPointer(

pointer: PointerObject<NoInfer<Omit<Fn, "nonblocking">>>,

definition: Fn,
)

новый

Параметры типа

Fn extends ForeignFunction

Свойства

call: FromForeignFunction<Fn>

Вызов внешней функции.

definition: Fn

Определение функции.

pointer: PointerObject<Fn>

Указатель на функцию.

класс Deno.UnsafePointer

Набор статических функций для работы с объектами-указателями.

Статические методы

create<T = unknown>(value: bigint): PointerValue<T>

Создает указатель из числового значения. Это действительно опасно!

equals<T = unknown>(

a: PointerValue<T>,

b: PointerValue<T>,
): boolean

Возвращает true, если оба указателя указывают на один адрес.

of<T = unknown>(value: Deno.UnsafeCallback | AllowSharedBufferSource): PointerValue<T>

Возвращает прямой указатель на массив типизированных данных в памяти.

offset<T = unknown>(

value: PointerObject,

offset: number,
): PointerValue<T>

Возвращает новый указатель со смещением относительно исходного на offset байт.

value(value: PointerValue): bigint

Получает числовое значение указателя

класс Deno.UnsafePointerView

Небезопасное представление области памяти, на которую указывает значение pointer. API UnsafePointerView соответствует стандартному встроенному интерфейсу DataView для доступа к типам, хранящимся в области памяти (числам, строкам и необработанным байтам).

Конструкторы

UnsafePointerView(pointer: PointerObject)

новый

Свойства

pointer: PointerObject

Методы

copyInto(

destination: AllowSharedBufferSource,

offset?: number,
): void

Копирует данные из памяти по указателю в массив типизированных данных.

Длина определяется по свойству byteLength массива типизированных данных.

Также принимает необязательное смещение в байтах относительно указателя.

getArrayBuffer(

byteLength: number,

offset?: number,
): ArrayBuffer

Получает ArrayBuffer длиной byteLength по заданному смещению в байтах относительно указателя.

getBigInt64(offset?: number): bigint

Получает знаковое 64-битное целое число по заданному смещению в байтах относительно указателя.

getBigUint64(offset?: number): bigint

Получает беззнаковое 64-битное целое число по заданному смещению в байтах относительно указателя.

getBool(offset?: number): boolean

Получает логическое значение по заданному смещению в байтах относительно указателя.

getCString(offset?: number): string

Получает строку в кодировке UTF-8 по заданному смещению в байтах, до нулевого байта.

Возвращаемая строка не включает символ U+0000.

Некорректные символы UTF-8 в возвращаемой строке заменяются символом U+FFFD.

getFloat32(offset?: number): number

Получает знаковое 32-битное число с плавающей запятой по заданному смещению в байтах относительно указателя.

getFloat64(offset?: number): number

Получает знаковое 64-битное число с плавающей запятой по заданному смещению в байтах относительно указателя.

getInt16(offset?: number): number

Получает знаковое 16-битное целое число по заданному смещению в байтах относительно указателя.

getInt32(offset?: number): number

Получает знаковое 32-битное целое число по заданному смещению в байтах относительно указателя.

getInt8(offset?: number): number

Получает знаковое 8-битное целое число по заданному смещению в байтах относительно указателя.

getPointer<T = unknown>(offset?: number): PointerValue<T>

Получает указатель по заданному смещению в байтах относительно указателя

getUint16(offset?: number): number

Получает беззнаковое 16-битное целое число по заданному смещению в байтах относительно указателя.

getUint32(offset?: number): number

Получает беззнаковое 32-битное целое число по заданному смещению в байтах относительно указателя.

getUint8(offset?: number): number

Получает беззнаковое 8-битное целое число по заданному смещению в байтах относительно указателя.

Статические методы

copyInto(

pointer: PointerObject,

destination: AllowSharedBufferSource,

offset?: number,
): void

Копирует данные из памяти по указанному указателю в массив типизированных данных.

Длина определяется по свойству byteLength массива типизированных данных.

Также принимает необязательное смещение в байтах относительно указателя.

getArrayBuffer(

pointer: PointerObject,

byteLength: number,

offset?: number,
): ArrayBuffer

Получает ArrayBuffer длиной byteLength по заданному смещению в байтах относительно указанного указателя.

getCString(

pointer: PointerObject,

offset?: number,
): string

Получает строку в кодировке UTF-8 по заданному смещению в байтах относительно указанного указателя, до нулевого байта.

Возвращаемая строка не включает символ U+0000.

Некорректные символы UTF-8 в возвращаемой строке заменяются символом U+FFFD.

функция Deno.dlopen

allow-ffi

dlopen<S extends ForeignLibraryInterface>(

filename: string | URL,

symbols: S,
): DynamicLibrary<S>

Открывает внешнюю динамическую библиотеку и регистрирует символы, делая доступными для вызова внешние функции.

Требуется разрешение allow-ffi. Загрузка внешних динамических библиотек теоретически может обойти все разрешения песочницы. Хотя это отдельное разрешение, на практике пользователям следует учитывать, что оно фактически эквивалентно запуску с разрешением allow-all.

Примеры

// Determine library extension based on
// your OS.
let libSuffix = "";
switch (Deno.build.os) {
  case "windows":
    libSuffix = "dll";
    break;
  case "darwin":
    libSuffix = "dylib";
    break;
  default:
    libSuffix = "so";
    break;
}

const libName = `./libadd.${libSuffix}`;
// Open library and define exported symbols
const dylib = Deno.dlopen(
  libName,
  {
    "add": { parameters: ["isize", "isize"], result: "isize" },
  } as const,
);

// Call the symbol `add`
const result = dylib.symbols.add(35n, 34n); // 69n

console.log(`Result from external addition of 35 and 34: ${result}`);

Параметры типа

S extends ForeignLibraryInterface

Параметры

filename: string | URL

symbols: S

Возвращаемый тип

DynamicLibrary<S>

интерфейс Deno.DynamicLibrary

Ресурс динамической библиотеки. Используйте Deno.dlopen, чтобы загрузить динамическую библиотеку и получить этот интерфейс.

Параметры типа

S extends ForeignLibraryInterface

Свойства

symbols: StaticForeignLibraryInterface<S>

Все зарегистрированные символы библиотеки вместе с функциями для их вызова.

Методы

close(): void

Удаляет указатели, связанные с символами библиотеки.

Продолжение использования символов, принадлежащих библиотеке, приведет к ошибкам и сбоям.

Вызов этого метода также немедленно обнуляет все ссылки и больше не препятствует завершению процесса Deno.

интерфейс Deno.ForeignFunction

Интерфейс внешней функции, определяемый типами ее параметров и результата.

Параметры типа

Parameters extends readonly NativeType[] = readonly NativeType[]

Result extends NativeResultType = NativeResultType

NonBlocking extends boolean = boolean

Свойства

name: string

необязательный

Имя символа.

По умолчанию используется имя ключа в объекте symbols.

parameters: Parameters

Параметры внешней функции.

result: Result

Результат (возвращаемое значение) внешней функции.

nonblocking: NonBlocking

необязательный

Если true, вызовы функции будут выполняться в выделенном блокирующем потоке и возвращать Promise, разрешающийся в result.

optional: boolean = false

необязательный

Если true, dlopen не завершится с ошибкой, если символ не найден. Вместо этого символу будет присвоено значение null.

интерфейс Deno.ForeignLibraryInterface

Дескриптор интерфейса внешней библиотеки.

Сигнатуры индекса

[name: string]: ForeignFunction | ForeignStatic

интерфейс Deno.ForeignStatic

Параметры типа

Type extends NativeType = NativeType

Свойства

name: string

необязательное

Имя символа; по умолчанию используется имя ключа в объекте symbols.

type: Type

Тип статического значения внешней библиотеки.

optional: boolean = false

необязательное

Если true, вызов dlopen не завершится ошибкой, если символ не найден. Вместо этого символу будет присвоено значение null.

интерфейс Deno.NativeStructType

Тип нативной структуры для взаимодействия с внешними функциями.

Свойства

struct: readonly NativeType[]

только для чтения

интерфейс Deno.PointerObject

Ненулевой указатель, представленный во время выполнения в виде объекта. Прототип объекта — null; его нельзя изменить. Объект нельзя присвоить ни одному значению, поэтому он полностью доступен только для чтения.

Для взаимодействия с памятью через указатель используйте класс UnsafePointerView. Чтобы создать указатель по адресу или получить адрес указателя, используйте статические методы класса UnsafePointer.

Параметры типа

T = unknown

Свойства

[brand]: T

интерфейс Deno.UnsafeCallbackDefinition

Определение небезопасной функции обратного вызова.

Параметры типа

Parameters extends readonly NativeType[] = readonly NativeType[]

Result extends NativeResultType = NativeResultType

Свойства

parameters: Parameters

Параметры функции обратного вызова.

result: Result

Текущий результат функции обратного вызова.

псевдоним типа Deno.ConditionalAsync

Параметры типа

IsAsync extends boolean | undefined

T

Определение

IsAsync extends true ? Promise<T> : T

псевдоним типа Deno.FromForeignFunction

Параметры типа

T extends ForeignFunction

Определение

T["parameters"] extends readonly [] ? () => StaticForeignSymbolReturnType<T> : (...args: ToNativeParameterTypes<T["parameters"]>) => StaticForeignSymbolReturnType<T>

псевдоним типа Deno.FromNativeParameterTypes

Параметры типа

T extends readonly NativeType[]

Определение

[T[number][]] extends [T] ? FromNativeType<T[number]>[] : [readonly T[number][]] extends [T] ? readonly FromNativeType<T[number]>[] : T extends readonly [...NativeType[]] ? [K in keyof T]: FromNativeType<T[K]> : never

псевдоним типа Deno.FromNativeResultType

Преобразование типов для возвращаемых значений внешних символов.

Параметры типа

T extends NativeResultType = NativeResultType

Определение

T extends NativeStructType ? Uint8Array<ArrayBuffer> : T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U : T extends NativeI8Enum<infer U> ? U : T extends NativeU16Enum<infer U> ? U : T extends NativeI16Enum<infer U> ? U : T extends NativeU32Enum<infer U> ? U : T extends NativeI32Enum<infer U> ? U : number : T extends NativeBigIntType ? bigint : T extends NativeBooleanType ? boolean : T extends NativePointerType ? T extends NativeTypedPointer<infer U> ? U | null : PointerValue : T extends NativeBufferType ? PointerValue : T extends NativeFunctionType ? T extends NativeTypedFunction<infer U> ? PointerObject<U> | null : PointerValue : T extends NativeVoidType ? void : never

псевдоним типа Deno.FromNativeType

Преобразование типов для возвращаемых значений внешних символов и параметров небезопасных функций обратного вызова.

Параметры типа

T extends NativeType = NativeType

Определение

T extends NativeStructType ? Uint8Array<ArrayBuffer> : T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U : T extends NativeI8Enum<infer U> ? U : T extends NativeU16Enum<infer U> ? U : T extends NativeI16Enum<infer U> ? U : T extends NativeU32Enum<infer U> ? U : T extends NativeI32Enum<infer U> ? U : number : T extends NativeBigIntType ? bigint : T extends NativeBooleanType ? boolean : T extends NativePointerType ? T extends NativeTypedPointer<infer U> ? U | null : PointerValue : T extends NativeBufferType ? PointerValue : T extends NativeFunctionType ? T extends NativeTypedFunction<infer U> ? PointerObject<U> | null : PointerValue : never

псевдоним типа Deno.NativeBigIntType

Все типы чисел BigInt для взаимодействия с внешними функциями.

Определение


"u64"
 | "i64"
 | "usize"
 | "isize"

псевдоним типа Deno.NativeBooleanType

Нативный логический тип для взаимодействия с внешними функциями.

Определение

"bool"

псевдоним типа Deno.NativeBufferType

Нативный тип буфера для взаимодействия с внешними функциями.

Определение

псевдоним типа Deno.NativeResultType

Определение

NativeType | NativeVoidType

псевдоним типа Deno.NativeType

Все поддерживаемые типы для взаимодействия с внешними функциями.

Определение


NativeNumberType
 | NativeBigIntType
 | NativeBooleanType
 | NativePointerType
 | NativeBufferType
 | NativeFunctionType
 | NativeStructType

Parameters extends readonly NativeType[] = readonly NativeType[]

Result extends NativeResultType = NativeResultType

Определение

Parameters extends readonly [] ? () => ToNativeResultType<Result> : (...args: FromNativeParameterTypes<Parameters>) => ToNativeResultType<Result>

переменная Deno.brand

Тип

unique symbol