thread

README

thread

Package thread provides threading facilities, such as scheduling calls on a specific thread, local storage, etc.

This package was previously published as golang.design/x/thread. It now lives in the golang.design/x/runtime module; update imports accordingly.

import "golang.design/x/runtime/thread"

Quick Start

th := thread.New()
defer th.Terminate()

// Run on the thread and block until it returns.
th.Call(func() {
    // ... runs on the created thread ...
})

// Schedule on the thread without waiting.
th.Go(func() {
    // ... runs on the created thread ...
})

// Run on the thread and return a typed value.
n := thread.Eval(th, func() int {
    return 42
})

License

MIT © 2020 - 2026 The golang.design Initiative

Documentation

Overview

Package thread provides threading facilities, such as scheduling calls on a specific thread, local storage, etc.

Index

• func Eval[T any](th Thread, fn func() T) T
• func EvalPool[T any](p *Pool, fn func() T) (T, bool)
• type Pool
  • func NewPool(n int) *Pool
  • func (p *Pool) Call(fn func()) bool
  • func (p *Pool) Go(fn func()) bool
  • func (p *Pool) Size() int
  • func (p *Pool) Terminate()
• type Thread
  • func New() Thread

Functions

func Eval

func Eval[T any](th Thread, fn func() T) T

Eval runs fn on the thread and returns its result. It blocks until fn returns. If the thread has been terminated, fn is discarded and Eval returns the zero value of T.

Eval is the typed counterpart of Call: it preserves fn's return type without an interface conversion or a type assertion at the call site.

th := thread.New()
n := thread.Eval(th, func() int { return 1 })

Eval is a function rather than a method of Thread because Go does not allow methods to declare their own type parameters.

func EvalPool

func EvalPool[T any](p *Pool, fn func() T) (T, bool)

EvalPool runs fn on some pool thread and returns its result. It blocks until fn returns. If the pool was terminated before fn could be accepted, it returns the zero value of T and false.

EvalPool is the typed counterpart of Pool.Call, mirroring Eval for a single Thread. It is a function rather than a method because Go does not allow methods to declare their own type parameters.

Types

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool is a bounded set of OS-locked threads that execute submitted work.

It bounds the number of OS threads a workload consumes by construction: instead of letting blocking calls each spin up a fresh thread (and then reactively reaping the surplus), all work is funneled onto a fixed number of threads the pool owns. Idle threads pick up the next task, so work is balanced across the pool without per-task scheduling.

func NewPool

func NewPool(n int) *Pool

NewPool creates a Pool backed by n threads. It panics if n <= 0.

func (*Pool) Call

func (p *Pool) Call(fn func()) bool

Call submits fn and blocks until it has run. It returns false without running fn if the pool was terminated before fn could be accepted, or if fn is nil.

func (*Pool) Go

func (p *Pool) Go(fn func()) bool

Go submits fn to run on some pool thread and returns true once a thread has accepted it. It blocks until an idle thread is available, providing backpressure that keeps in-flight work bounded by the pool size. It returns false without running fn if the pool was terminated first, or if fn is nil.

A task that has been accepted always runs to completion, even if the pool is terminated meanwhile; only not-yet-accepted tasks are discarded.

func (*Pool) Size

func (p *Pool) Size() int

Size returns the number of threads in the pool.

func (*Pool) Terminate

func (p *Pool) Terminate()

Terminate stops every thread in the pool and discards any not-yet-accepted tasks. It is safe to call multiple times, including concurrently.

type Thread

type Thread interface {
	// ID returns the ID of the thread.
	ID() uint64

	// Call runs fn on the thread and blocks until fn returns.
	// If the thread has been terminated, fn is discarded and Call
	// returns immediately without running it.
	//
	// If Terminate may run concurrently with Call, Call can return
	// before fn finishes (the call is abandoned). In that case a value
	// that fn writes to a captured variable must not be read after Call
	// returns, as fn may still be writing it. Use Eval, which returns
	// fn's result safely, when you need a value back.
	Call(fn func())

	// Go schedules fn to run on the thread without waiting for it to
	// complete. If the thread has been terminated, fn is discarded.
	Go(fn func())

	// SetTLS stores a value in the thread's local storage. It must be
	// called from within Call, Go, or Eval so the access happens on the
	// thread itself. For instance:
	//
	//   th := thread.New()
	//   th.Call(func() {
	//      th.SetTLS("store in thread local storage")
	//   })
	SetTLS(x any)

	// GetTLS returns the value stored in the thread's local storage. It
	// must be called from within Call, Go, or Eval so the access happens
	// on the thread itself. For instance:
	//
	//   th := thread.New()
	//   th.Call(func() {
	//      tls := th.GetTLS()
	//      // ... do whatever you want to do with the tls value ...
	//   })
	GetTLS() any

	// Terminate terminates the thread gracefully.
	// Scheduled but unexecuted calls are discarded.
	// It is safe to call Terminate multiple times, including
	// concurrently from multiple goroutines.
	Terminate()
}

Thread represents a thread instance.

func New

func New() Thread

New creates a new thread instance.