Struct ThreadBuilder 

pub struct ThreadBuilder { /* private fields */ }

Builder for creating new threads with specific configurations.

ThreadBuilder follows the builder pattern to construct a Thread with custom stack sizes, priority, CPU affinity, TLS base, and filesystem state. The build method allocates physical frames for both user and kernel stacks, assigns virtual address regions with guard pages, and initializes the thread’s CPU context.

Example

let thread = ThreadBuilder::new(pid, "worker".into(), entry_fn as usize)
    .user_stack_size(2 * 1024 * 1024)  // 2 MB user stack
    .priority(3)
    .cpu_affinity(0x3)                  // CPUs 0 and 1
    .build()?;

Defaults

• User stack: 1 MB
• Kernel stack: 64 KB
• Priority: 2 (normal)
• CPU affinity: all CPUs (usize::MAX)
• TLS base: None (no TLS)
• Filesystem state: new root (“/”, umask 0o022)

Implementations

impl ThreadBuilder

pub fn new(process: ProcessId, name: String, entry_point: usize) -> Self

Create a new thread builder with required parameters.

Arguments

• process: The parent process ID that owns this thread.
• name: Human-readable thread name (for debugging/logging).
• entry_point: Virtual address where thread execution begins.

pub fn user_stack_size(self, size: usize) -> Self

Set user stack size

pub fn kernel_stack_size(self, size: usize) -> Self

Set kernel stack size

pub fn priority(self, priority: u8) -> Self

Set priority

pub fn cpu_affinity(self, mask: usize) -> Self

Set CPU affinity

pub fn clear_tid(self, ptr: usize) -> Self

Set clear_tid pointer for CLONE_CHILD_CLEARTID

pub fn fs(self, fs: Arc<ThreadFs>) -> Self

Set the filesystem view (cwd/umask) for the new thread.

When creating a thread via clone() with CLONE_FS, pass a shared Arc<ThreadFs> from the parent. Without CLONE_FS, pass a copy via ThreadFs::clone_copy. If not set, the builder defaults to a new root filesystem state.

pub fn tls_base(self, base: usize) -> Self

Set the TLS (Thread-Local Storage) base address for the new thread.

This corresponds to CLONE_SETTLS on Linux or arch_prctl(ARCH_SET_FS) on x86_64. The base address is written into the architecture-specific TLS register (FS base on x86_64, TPIDR_EL0 on AArch64, tp on RISC-V) when the thread is first scheduled.

pub fn build(self) -> Result<Thread, KernelError>

Build the thread with real stack allocation.

Allocates physical frames for the kernel stack via the global frame allocator. User stack frames are NOT allocated here because every caller immediately maps user stack pages through the VAS (via map_page()), which allocates its own tracked frames. Allocating frames here would orphan them (never freed, never used), leaking 64 pages (256 KB) per thread – the root cause of the native-compilation OOM.

Kernel stack frames are stored in Stack::phys_frame so that cleanup_process() can free them without walking page tables.

Each stack gets a guard page (unmapped) below it to detect overflow. Stack pointers are set to the top of each allocated region since stacks grow downward on all supported architectures (x86_64, AArch64, RISC-V).