Crate go_lib 

go-lib

Go-style concurrency for Rust: goroutines, channels, select, WaitGroup — built on a port of the M:N scheduler from https://github.com/golang/go.

No async runtime is used: the scheduler, channels, and parking primitives are ported from src/runtime/ in the Go repo. Mutexes and read-write locks are taken straight from std::sync because their uncontended path is just an atomic CAS — porting Go’s versions would be code without benefit. See [runtime::syscall] for the shim that keeps std blocking calls scheduler-safe.

Public surface

• go! / select! macros — spawn goroutines, multiplex channel ops
• chan — buffered and unbuffered channels
• net — goroutine-aware TcpListener / TcpStream (v2.0)
• sync::WaitGroup — wait for a collection of goroutines
• sync::Cond — goroutine-aware condition variable
• sync::Mutex / sync::RwLock — re-exports of std::sync
• context — cancellation and deadline propagation
• set_panic_handler — customise goroutine-panic behaviour
• set_gomaxprocs / gomaxprocs — runtime parallelism control

Internals

See runtime for the scheduler (G/M/P, parking, work stealing, sysmon, stack growth, async preemption, netpoll).

v2.0 — new in this release

• Dynamic stack growth (Step 3): goroutines start with an 8 KiB stack and grow automatically up to 1 GiB via SIGSEGV guard-page detection and copystack (conservative pointer adjustment).
• Async preemption (Step 4): sysmon sends SIGURG to the M thread whose goroutine has run > 10 ms. The signal handler redirects execution to an assembly trampoline that saves all registers, calls async_preempt2, and restores state on resume — a transparent, non-cooperative yield.
• Netpoll / async I/O (Step 5): epoll on Linux, kqueue on macOS. Goroutines park on EAGAIN and are re-enqueued when the fd is ready. See the net module for TcpListener / TcpStream.

Known limitations

defer / recover / cross-goroutine panic

Goroutine panics are caught and routed to set_panic_handler; the process does not abort. Go’s recover() (stopping panic propagation at a call-stack boundary) has no direct Rust equivalent — use catch_unwind inside the goroutine body when fine-grained recovery is needed.

Race detector

The Go race detector is a compiler/runtime feature with no Rust equivalent in this crate. Use cargo test --cfg loom with the [loom model checker] for systematic concurrency testing.

Unsafe conventions

The runtime modules (src/runtime/) are a direct port of Go’s C-adjacent runtime code. Almost every function is unsafe fn because it operates on raw goroutine pointers and mmap’d memory. Inner unsafe {} blocks are omitted for brevity (suppressed via unsafe_op_in_unsafe_fn) — the caller’s obligation is documented in each function’s # Safety section instead.

Modules

chan

Channels — ported from src/runtime/chan.go.

context

Cancellation and deadline propagation — equivalent to Go’s context package.

net

Goroutine-aware TCP networking (Step 5: netpoll integration).

runtime

Goroutine scheduler internals.

select

selectgo — the runtime heart of select { }.

sync

Synchronization primitives.

Macros

go

Spawn a closure as a new goroutine.

select

Multiplex channel operations.

Functions

gomaxprocs

Return the current number of logical processors (GOMAXPROCS).

gosched

Yield the CPU, giving other goroutines a chance to run.

run

Initialise the go-lib scheduler and run f as the first goroutine.

set_gomaxprocs

Set the number of logical processors and return the previous value.

set_panic_handler

Register a custom handler for goroutine panics.

sleep

Sleep the current goroutine for at least d.

with_syscall

Wrap a potentially-blocking operation so the go-lib scheduler can hand off this goroutine’s P to another M while the OS thread is in the kernel.