Buffer 实现

相关源文件

• bench/snippets/buffer-fill.mjs
• src/base64/base64.zig
• src/bun.js/bindings/JSBuffer.cpp
• src/bun.js/bindings/NodeValidator.h
• src/bun.js/modules/NodeBufferModule.h
• src/bun.js/node/buffer.zig
• src/bun.js/webcore/ObjectURLRegistry.zig
• src/js/builtins/JSBufferConstructor.ts
• src/js/builtins/JSBufferPrototype.ts
• test/js/node/buffer-resolveObjectURL.test.ts
• test/js/node/buffer.test.js
• test/js/node/test/parallel/test-buffer-bigint64.js

本文档介绍了 Bun 对 Node.js 兼容的 Buffer 实现，该实现基于 JavaScriptCore 的 JSUint8Array 构建，提供了一个二进制数据抽象。该实现横跨多种语言（C++、Zig、TypeScript），并包含编码/解码支持、内存管理和性能优化。

有关 Buffer 上下文之外的字符串处理和文本编码信息，请参阅 字符串处理与文本编码。有关 JavaScript 运行时内存管理的详细信息，请参阅 JavaScript VM 生命周期。

架构概述

Bun 的 Buffer 实现是一个多层系统，它通过 Node.js 兼容的功能扩展了 JavaScriptCore 的类型化数组。

来源： src/bun.js/bindings/JSBuffer.cpp1-100 src/js/builtins/JSBufferConstructor.ts1-46 src/js/builtins/JSBufferPrototype.ts1-50 src/bun.js/modules/NodeBufferModule.h1-50

核心组件和代码实体

Buffer 实现由几个关键组件构成，它们协同工作以提供完整的功能。

来源： src/bun.js/bindings/JSBuffer.cpp91-116 src/bun.js/bindings/JSBuffer.cpp220-259 src/bun.js/bindings/JSBuffer.cpp378-415 src/bun.js/bindings/JSBuffer.cpp279-296

Buffer 创建与分配

Buffer 实例可以通过多种途径创建，每种途径都针对不同的用例进行了优化。

分配策略

方法	功能	内存初始化	用例
Buffer.alloc()	allocBuffer	零填充	安全分配
Buffer.allocUnsafe()	allocBufferUnsafe	未初始化	性能关键
Buffer.allocUnsafeSlow()	allocBufferUnsafe	未初始化	非池化分配
Buffer.from()	constructFromEncoding	数据初始化	从现有数据创建

分配函数会创建具有自定义子类结构的 JSUint8Array 实例。

来源： src/bun.js/bindings/JSBuffer.cpp617-711 src/bun.js/bindings/JSBuffer.cpp220-239 src/bun.js/bindings/JSBuffer.cpp241-259

编码支持

Bun 的 Buffer 实现通过统一的编码系统支持多种文本编码。

支持的编码

BufferEncodingType 枚举定义了支持的编码。

• utf8：UTF-8 编码（默认）
• ascii：7 位 ASCII
• latin1/binary：ISO-8859-1
• base64：Base64 编码
• base64url：URL 安全 Base64
• hex：十六进制编码
• utf16le/ucs2：UTF-16 小端序
• buffer：原始二进制数据

编码操作

来源： src/bun.js/bindings/JSBuffer.cpp378-415 src/bun.js/bindings/JSBuffer.cpp279-296 src/base64/base64.zig1-60

Base64 实现

Base64 编码/解码使用 Zig 实现，并进行了 SIMD 优化。

Base64 特性

• 标准 Base64：符合 RFC 4648 标准
• URL 安全 Base64：RFC 4648 第 5 部分
• 容错解码：忽略空格和无效字符
• SIMD 加速：使用 simdutf 库以获得高性能

来源： src/base64/base64.zig17-35 src/base64/base64.zig47-49 src/base64/base64.zig72-74

内存管理与 Buffer 生命周期

Buffer 实例通过 JavaScriptCore 的垃圾回收系统进行管理。

内存分配模式

分配类型	内存来源	释放
小 Buffer	池化分配	GC 管理
大 Buffer	直接分配	GC 管理
外部数据	自定义释放器	基于回调

Buffer 子类化

Buffer 实现为 JSUint8Array 的子类，并具有自定义结构。

来源： src/bun.js/bindings/JSBuffer.cpp227-238 src/bun.js/bindings/JSBuffer.cpp353-373 src/bun.js/bindings/JSBuffer.cpp417-421

性能优化

Buffer 实现包含多项性能优化。

向量化操作

Zig 中的 BufferVectorized 模块提供了优化的 fill 操作。

DataView 缓存

Buffer 原型方法缓存 DataView 实例以提高性能。

来源： src/bun.js/node/buffer.zig8-85 src/js/builtins/JSBufferPrototype.ts4-23 src/js/builtins/JSBufferPrototype.ts19-23

验证和错误处理

Buffer 实现通过 NodeValidator 系统提供了全面的验证

验证函数

• validateInteger()：验证整数参数
• validateOffset()：验证 Buffer 偏移量
• parseEncoding()：验证编码字符串
• validateArrayBufferView()：验证类型化数组输入

错误处理遵循 Node.js 的约定，并带有特定的错误代码

• ERR_INVALID_ARG_TYPE：无效的参数类型
• ERR_OUT_OF_RANGE：值超出有效范围
• ERR_UNKNOWN_ENCODING：不支持的编码类型

来源： src/bun.js/bindings/JSBuffer.cpp298-321 src/bun.js/bindings/NodeValidator.h32-54 src/bun.js/bindings/JSBuffer.cpp279-296