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 (v0.2.0)
• [scope] / scope::Scope — scoped goroutines with safe short-lived borrows
• 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).

v0.4.0 — new in this release

• scope / ScopedJoinHandle: scoped goroutines with safe short-lived borrows, mirroring std::thread::scope. Goroutines spawned inside a scope closure can borrow data from the enclosing stack frame; the scheduler guarantees every spawned goroutine finishes before scope returns. ScopedJoinHandle::join() returns std::thread::Result<R> so goroutine panics surface as Err rather than aborting the process.
• Channel double-free fix: the blocking-receive resume path in chanrecv used ptr::read followed by Box::from_raw on the same allocation, which double-dropped the inner value and caused use-after-free when the moved-out value was later inspected (e.g. a panic payload passed through a scoped join handle). Fixed by casting the Box to ManuallyDrop<Option<T>> before dropping, so only the heap allocation is freed without re-running the destructor.

v0.3.1 — new in this release

• G state machine: casgstatus centralises all goroutine status transitions. GSYSCALL, GCOPYSTACK, GPREEMPTED, and GSCAN are now wired into entersyscall/exitsyscall, copystack, and preemptm respectively, matching Go 1.14+ semantics.
• systemstack: runs a closure on the M’s g0 (system) stack via a naked-assembly RSP/SP switch. Implemented for both AMD64 (SysV + Windows x64) and AArch64 (AAPCS64).

v0.2.0 — new in this release

• Dynamic stack growth (Step 3): goroutines start with a 64 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, IOCP on Windows. Goroutines park on blocking I/O and are re-enqueued when the operation is ready (Unix) or completes (Windows IOCP). 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.

scope

Scoped goroutines — safe short-lived borrows.

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, run f as the first goroutine, and return whatever f returns.

scope

Spawn short-lived goroutines that can borrow data from the calling scope.

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.

Attribute Macros

run

Attribute macro that wraps a function body in [run].