Subprocess Management

Relevant source files

• packages/bun-usockets/src/bsd.c
• packages/bun-usockets/src/context.c
• packages/bun-usockets/src/crypto/openssl.c
• packages/bun-usockets/src/eventing/epoll_kqueue.c
• packages/bun-usockets/src/internal/internal.h
• packages/bun-usockets/src/internal/networking/bsd.h
• packages/bun-usockets/src/libusockets.h
• packages/bun-usockets/src/loop.c
• packages/bun-usockets/src/socket.c
• packages/bun-uws/src/App.h
• packages/bun-uws/src/AsyncSocket.h
• packages/bun-uws/src/HttpContext.h
• packages/bun-uws/src/HttpResponse.h
• packages/bun-uws/src/HttpResponseData.h
• packages/bun-uws/src/Loop.h
• packages/bun-uws/src/LoopData.h
• src/bun.js/api/bun/socket.zig
• src/bun.js/api/bun/subprocess.zig
• src/bun.js/api/server.zig
• src/bun.js/bindings/BunJSCEventLoop.cpp
• src/bun.js/bindings/BunProcess.cpp
• src/bun.js/bindings/BunProcess.h
• src/bun.js/bindings/helpers.cpp
• src/bun.js/event_loop/GarbageCollectionController.zig
• src/bun.js/modules/BunObjectModule.h
• src/bun.js/modules/ObjectModule.h
• src/bun.js/webcore/streams.zig
• src/deps/_libusockets.h
• src/deps/libuwsockets.cpp
• src/deps/uws.zig
• src/http.zig
• src/js/builtins/ImportMetaObject.ts
• src/js/builtins/ProcessObjectInternals.ts
• src/js/builtins/ReadableStreamInternals.ts
• test/cli/run/require-cache-bug-5188.js
• test/cli/run/require-cache.test.ts
• test/js/bun/http/bun-server.test.ts
• test/js/bun/http/bun-websocket-cpu-fixture.js
• test/js/bun/http/serve.test.ts
• test/js/bun/net/kqueue-filter-coalesce-fixture.ts
• test/js/bun/net/socket.test.ts
• test/js/node/process/process.test.js
• test/js/node/test/parallel/test-process-setsourcemapsenabled.js
• test/js/node/test/parallel/test-resource-usage.js
• test/js/web/fetch/fetch.test.ts
• test/regression/issue/26377.test.ts

This page documents Bun's subprocess management system, which provides the Bun.spawn() and Bun.spawnSync() APIs for creating and managing child processes. This includes process lifecycle management, stdio redirection, IPC (inter-process communication), resource tracking, and platform-specific process spawning.

For server-side HTTP/WebSocket functionality, see Server and Networking Architecture. For lower-level socket operations, see Socket and Network Layer.

Overview and Core Components

The subprocess system is implemented primarily in Zig and provides both synchronous and asynchronous process spawning. The main entry point is the Subprocess struct, which wraps the underlying platform process and manages stdio streams, IPC channels, resource usage tracking, and process lifecycle.

Sources: src/bun.js/api/bun/subprocess.zig1-100 src/bun.js/api/bun/subprocess.zig267-270

Subprocess Structure and Lifecycle

The Subprocess struct is the core data structure that represents a spawned child process. It maintains reference counting, manages process state, and coordinates between the JavaScript API surface and the underlying OS process.

Key Fields and State Management

Sources: src/bun.js/api/bun/subprocess.zig4-62 src/bun.js/api/bun/subprocess.zig145-193

Process Lifecycle Events

The subprocess lifecycle is managed through a series of callbacks that handle process state transitions:

The onProcessExit callback is the central handler for process termination:

• Captures exit status (code, signal, or error)
• Stores resource usage (Rusage) for later retrieval
• Closes stdin pipe writer
• Triggers stdout/stderr read completion
• Resolves exited promise or calls onExit callback
• Disconnects IPC channel
• Cancels timeout timer
• Updates pending activity state

Sources: src/bun.js/api/bun/subprocess.zig569-680 src/bun.js/api/bun/subprocess.zig311-358 src/bun.js/api/bun/subprocess.zig395-421

Stdio Stream Management

Bun provides flexible stdio handling through the Writable (stdin) and Readable (stdout/stderr) union types. Each stream can be configured as a pipe, buffer, or ignored.

Stdin (Writable) Variants

The StaticPipeWriter handles writing data to the subprocess stdin. It can write from:

• Blob sources: File data or in-memory blobs
• ArrayBuffer sources: JavaScript TypedArrays held by GC
• Streams: When is_stdin_a_readable_stream flag is set

Sources: src/bun.js/api/bun/subprocess.zig497-532 src/bun.js/api/bun/subprocess/StaticPipeWriter.zig1-50

Stdout/Stderr (Readable) Variants

The PipeReader reads from stdout/stderr asynchronously:

• Maintains a buffer that grows as data arrives
• Uses Async.FilePoll for event-driven I/O
• Transitions from pending (accumulating) to done (complete)
• Can be converted to JavaScript values (string, Buffer, Blob)

Sources: src/bun.js/api/bun/subprocess.zig272-302 src/bun.js/api/bun/subprocess/SubprocessPipeReader.zig1-100

Stdio Access Patterns

The observable_getters tracks which stdio streams have been accessed from JavaScript, affecting reference counting and cleanup behavior.

Sources: src/bun.js/api/bun/subprocess.zig274-309 src/bun.js/api/bun/subprocess.zig402-404

IPC (Inter-Process Communication)

Bun provides IPC capabilities for bidirectional message passing between parent and child processes. This is used when the subprocess is spawned with the ipc option enabled.

IPC Architecture

IPC Message Flow

Key IPC operations:

• doSend(): Sends a message to the child process via IPC.doSend()
• disconnect(): Closes the IPC channel, triggering onDisconnectCallback
• getConnected(): Returns whether the IPC channel is active

Sources: src/bun.js/api/bun/subprocess.zig437-457 src/bun.js/api/bun/subprocess.zig36-38

Process Control and Signals

Subprocesses can be killed, timed out, or aborted using various mechanisms.

Signal Handling

Timeout Management

Subprocesses can have a timeout configured that automatically kills the process if it runs too long:

The timeout uses event_loop_timer which is integrated with Bun's event loop timer system. The timer is reference-counted to prevent the event loop from exiting while a timeout is pending.

Sources: src/bun.js/api/bun/subprocess.zig364-390 src/bun.js/api/bun/subprocess.zig338-358 src/bun.js/api/bun/subprocess.zig44-49

AbortSignal Integration

When an AbortSignal is provided during spawn, it's stored and monitored. When aborted, it triggers onAbortSignal() which clears the signal reference and attempts to kill the process with the configured killSignal.

Sources: src/bun.js/api/bun/subprocess.zig111-115 src/bun.js/api/bun/subprocess.zig41-42

Resource Management

Reference Counting and Cleanup

The subprocess uses a reference counting scheme to ensure proper cleanup:

The updateHasPendingActivity() method determines if the subprocess should keep the event loop alive based on:

• Whether the process has exited
• Whether stdio streams have pending reads/writes
• Whether IPC is connected

Sources: src/bun.js/api/bun/subprocess.zig11-14 src/bun.js/api/bun/subprocess.zig149-179 src/bun.js/api/bun/subprocess.zig423-435

Resource Usage Tracking

Resource usage is captured at process exit and exposed through the resourceUsage() method, which returns a JavaScript object with CPU and memory statistics.

Sources: src/bun.js/api/bun/subprocess.zig117-143 src/bun.js/api/bun/subprocess.zig86-87 src/bun.js/api/bun/subprocess.zig21-22

Platform-Specific Implementation

Process Spawning

Stdio Platform Differences

On POSIX systems:

• Stdio uses file descriptors (bun.FileDescriptor)
• Pipes created with pipe() or pipe2()
• Non-blocking I/O with O_NONBLOCK
• Polling via Async.FilePoll (epoll/kqueue)

On Windows:

• Stdio uses StdioResult which wraps handles
• Pipes are OVERLAPPED handles or libuv streams
• Named pipes for stdio redirection
• I/O completion ports for async operations

Sources: src/bun.js/api/bun/subprocess.zig20-21 src/bun.js/api/bun/subprocess.zig76-84

MaxBuffer Enforcement

The maxBuffer option limits the amount of data buffered from stdout/stderr, preventing unbounded memory growth:

When the buffer size exceeds maxBuffer, the subprocess is immediately killed with the configured killSignal. The exited_due_to_maxbuf field tracks which stream (stdout or stderr) triggered the limit.

Sources: src/bun.js/api/bun/subprocess.zig359-362 src/bun.js/api/bun/subprocess.zig50-52

Synchronous vs Asynchronous Spawning

Bun supports both async (Bun.spawn()) and sync (Bun.spawnSync()) subprocess spawning:

Feature	Async (Bun.spawn)	Sync (Bun.spawnSync)
Process polling	Event-driven via Async.FilePoll or libuv	Blocking wait
Stdio handling	Streams with async I/O	Buffered, read at end
Event loop	Keeps loop alive if has pending activity	Blocks event loop
Memory tracking	this_value uses weak ref when no pending activity	N/A (returns immediately)
IPC	Full bidirectional support	Not supported
Callbacks	onExit, onMessage, etc.	Return object only

The is_sync flag in the Flags struct controls the behavior throughout the lifecycle.

Sources: src/bun.js/api/bun/subprocess.zig54-62 src/bun.js/api/bun/subprocess.zig615-634

Terminal/PTY Support

When spawned with the terminal option, a subprocess can be attached to a pseudo-terminal (PTY):

When a terminal is present, the normal stdio getters (stdin, stdout, stderr) return null in JavaScript, and all I/O goes through the terminal getter instead.

Sources: src/bun.js/api/bun/subprocess.zig24-25 src/bun.js/api/bun/subprocess.zig274-309

Error Handling and Exit Codes

Exit status is captured and exposed to JavaScript as a resolved or rejected promise:

Signal-based exits return 128 + signal_number to match POSIX shell conventions.

Sources: src/bun.js/api/bun/subprocess.zig569-680 src/bun.js/api/bun/subprocess.zig545-567