fibjs is a JavaScript runtime built on Chrome's V8 engine (v11.8.173) that enables high-performance server-side JavaScript applications using a fiber-based cooperative multitasking model. Unlike traditional Node.js callback-style or async/await patterns, fibjs allows developers to write synchronous-looking code that executes with fully asynchronous I/O underneath, eliminating callback hell while maintaining non-blocking performance.
This document provides an architectural overview of the fibjs runtime system. For detailed information about specific subsystems, see:
The fibjs runtime is organized into five main architectural layers, each with specific responsibilities for execution, I/O, and module management.
Sources: fibjs/src/base/Runtime.cpp1-198 fibjs/include/Isolate.h1-354 fibjs/src/coroutine/Fiber.cpp1-276 fibjs/include/AsyncCall.h1-501 fibjs/src/base/acPool.cpp1-358 README.md1-48
The core innovation in fibjs is the JSFiber class, which implements cooperative multitasking using fibers (lightweight user-space threads). This allows thousands of concurrent operations without the overhead of OS threads or the complexity of callback chains.
Sources: fibjs/src/coroutine/Fiber.cpp1-276 fibjs/src/base/acPool.cpp20-107 fibjs/include/AsyncCall.h10-93
| Class | Location | Purpose |
|---|---|---|
JSFiber | fibjs/src/coroutine/Fiber.cpp19 | Represents a single fiber of execution with its own stack and context |
Isolate | fibjs/include/Isolate.h49 | V8 isolate wrapper managing fiber pools, job queues, and execution contexts |
AsyncEvent | fibjs/include/AsyncCall.h11 | Base class for asynchronous operations that can be dispatched to worker pools |
AsyncCall | fibjs/include/AsyncCall.h94 | Synchronous-style async call that suspends fiber until completion |
AsyncCallBack | fibjs/include/AsyncCall.h423 | Callback-based async call for traditional Node.js-style APIs |
acPool | fibjs/src/base/acPool.cpp20 | Worker pool managing background I/O operations |
Sources: fibjs/src/coroutine/Fiber.cpp1-276 fibjs/include/Isolate.h49-354 fibjs/include/AsyncCall.h1-501 fibjs/src/base/acPool.cpp20-358
The magic of fibjs is the AsyncCall system that converts synchronous-looking API calls into truly asynchronous operations. When an I/O operation cannot complete immediately, it returns CALL_E_NOSYNC, which triggers fiber suspension and background processing.
Sources: fibjs/include/AsyncCall.h94-155 fibjs/src/base/acPool.cpp73-100 fibjs/include/Isolate.h66-76
fibjs uses a comprehensive result_t (int32_t) return code system to signal operation status:
| Result Code | Value Range | Meaning |
|---|---|---|
CALL_E_NOSYNC | -20017 | Operation must be async, suspend fiber |
CALL_E_LONGSYNC | -20018 | Long-running sync operation, use thread pool |
CALL_E_GUICALL | -20019 | GUI operation, dispatch to GUI thread |
CALL_E_PENDDING | -20015 | Operation pending, callback will fire |
CALL_E_EXCEPTION | -20024 | JavaScript exception occurred |
| Positive values | >0 | Success, may indicate special return values |
| Negative values | <-20000 | Error codes |
Sources: fibjs/include/utils.h112-176 fibjs/src/base/utils.cpp50-149
fibjs exposes C++ objects to JavaScript using the object_base class hierarchy and the ClassInfo metadata system. This allows native objects to participate in V8 garbage collection while maintaining proper lifecycle management.
Sources: fibjs/include/object.h28-481 fibjs/include/ClassInfo.h94-595 fibjs/src/base/Isolate.cpp63-80
fibjs provides a comprehensive macro system for defining class bindings:
DECLARE_CLASS(MyClass) - Declare class with reference counting
DECLARE_CLASSINFO(MyClass) - Declare ClassInfo accessor
METHOD_ENTER() - Begin method definition with argument parsing
METHOD_OVER(required, optional) - Define method overload
ARG(type, index) - Extract typed argument
METHOD_RETURN() - Return value and handle errors
Sources: fibjs/include/utils.h442-473 fibjs/include/object.h28-563
The SandBox class provides isolated execution contexts for loading and running JavaScript modules with support for CommonJS, ES modules, TypeScript, and custom loaders.
Sources: fibjs/include/SandBox.h fibjs/src/base/SandBox.cpp fibjs/include/Isolate.h343-345
The fibjs runtime initializes through a multi-stage bootstrap process that sets up the V8 engine, fiber pools, and platform services.
Sources: fibjs/program/src/app.cpp13-51 fibjs/src/base/Runtime.cpp43-178 fibjs/src/base/Isolate.cpp156-370 fibjs/src/base/acPool.cpp329-333
| Stage | Function | File | Purpose |
|---|---|---|---|
| 1 | main() | app.cpp13 | Entry point, registers native modules |
| 2 | start() | Runtime.cpp73 | Spawns entry thread with argument processing |
| 3 | createBasisForFiberLoop() | Runtime.cpp43 | Initializes worker pools, I/O threads, V8 platform |
| 4 | new Isolate() | Isolate.cpp156 | Creates V8 isolate, first fiber, HTTP client |
| 5 | Isolate::init() | Isolate.cpp336 | Sets up V8 context, global template, built-in modules |
| 6 | FiberProcJsEntry | fibjs.cpp | Executes user's entry script |
Sources: fibjs/program/src/app.cpp13-51 fibjs/src/base/Runtime.cpp43-178 fibjs/src/base/Isolate.cpp156-370
fibjs supports a wide range of platforms and architectures through a unified CMake-based build system and Docker-based CI/CD pipeline.
Sources: .github/workflows/build.yml1-161 fibjs/CMakeLists.txt1-35 BUILDING.md1-198
| Platform | Architectures | Test Status | Build Environment |
|---|---|---|---|
| Linux | x64, ia32, arm, arm64, mips64, ppc64, riscv64, loong64 | ✓ Tested | Docker ubuntu-22.04 |
| Alpine | x64, ia32, arm64 | ✓ Tested | Docker alpine-build-env |
| Windows | x64, ia32, arm64 | ✓ Tested (arm64: build-only) | windows-2022 + LLVM |
| macOS | x64, arm64 | ✓ Tested | macos-15 |
| Android | x64, ia32, arm, arm64 | ✓ Tested (ia32/arm: build-only) | Docker android-build-env |
| iOS | arm64, simulator x64/arm64 | Build-only | macos-15 + Xcode |
Sources: .github/workflows/build.yml27-124 BUILDING.md4-148
| Metric | Value | Source |
|---|---|---|
| Version | 0.38.0-dev | fibjs/include/version.h10 |
| V8 Version | 11.8.173 | README.md12 |
| JSC Version | 0x0F1B0001 | fibjs/include/version.h11 |
| Built-in Modules | 50+ | test/main.js1-114 |
| Test Cases | 857+ | test/main.js1-114 |
| Supported Platforms | 9 architectures × 5 OS types | .github/workflows/build.yml27-124 |
| Stream Buffer Size | 65536 bytes | fibjs/include/utils.h192 |
| Default Max Listeners | 10 per EventEmitter | fibjs/src/base/Isolate.cpp168 |
| Fiber Stack Size | Configurable (default 256KB start, 128KB workers) | fibjs/src/coroutine/Fiber.cpp18 acPool.cpp18 |
Sources: fibjs/include/version.h10-11 README.md12 test/main.js1-114 fibjs/include/utils.h192 fibjs/src/base/Isolate.cpp168 fibjs/src/coroutine/Fiber.cpp18 fibjs/src/base/acPool.cpp18
fibjs provides an extensive standard library organized into functional categories:
| Category | Modules | Purpose |
|---|---|---|
| Core I/O | fs, net, dgram, http, https, ws, sse | File system, networking, HTTP/WebSocket servers |
| Concurrency | coroutine, worker_threads, child_process | Fibers, workers, process spawning |
| Crypto | crypto, webcrypto, tls, hash | Cryptography, TLS/SSL, hashing |
| Data Formats | json, xml, encoding, zlib, mime, querystring | Serialization, compression, text encoding |
| Databases | db, LevelDB, SQLite, MySQL, ODBC | Database drivers |
| System | process, os, path, util, console | System APIs, utilities |
| Runtime | vm, SandBox, module | Script execution, sandboxing |
| GUI | gui, WebView | Desktop application support |
| Testing | assert, test | Unit testing framework |
| Advanced | wasm, fasttext, vector | WebAssembly, ML, vector operations |
Sources: test/main.js1-114 README.md30-34
This overview establishes the foundation for understanding fibjs. The following sections dive deeper into each subsystem, providing implementation details, code references, and usage patterns for developers working with or extending the runtime.
Refresh this wiki