thread

README

thread

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

import "golang.design/x/thread"

Quick Start

th := thread.New()

th.Call(func() {
    // call on the created thread
})

License

MIT © 2021 The golang.design Initiative

Documentation

Overview

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

Index

• type Thread
  • func New() Thread

Types

type Thread

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

	// Call calls fn from the given thread. It blocks until fn returns.
	Call(fn func())

	// CallNonBlock call fn from the given thread without waiting
	// fn to complete.
	CallNonBlock(fn func())

	// CallV call fn from the given thread and returns the returned
	// value from fn.
	//
	// The purpose of this function is to avoid value escaping.
	// In particular:
	//
	//   th := thread.New()
	//   var ret interface{}
	//   th.Call(func() {
	//      ret = 1
	//   })
	//
	// will cause variable ret be allocated on the heap, whereas
	//
	//   th := thread.New()
	//   ret := th.CallV(func() interface{} {
	//     return 1
	//   }).(int)
	//
	// will offer zero allocation benefits.
	CallV(fn func() interface{}) interface{}

	// SetTLS stores a given value to the local storage of the given
	// thread. This method must be accessed in Call, or CallV, or
	// CallNonBlock. For instance:
	//
	//   th := thread.New()
	//   th.Call(func() {
	//      th.SetTLS("store in thread local storage")
	//   })
	SetTLS(x interface{})

	// GetTLS returns the locally stored value from local storage of
	// the given thread. This method must be access in Call, or CallV,
	// or CallNonBlock. For instance:
	//
	//   th := thread.New()
	//   th.Call(func() {
	//      tls := th.GetTLS()
	//      // ... do what ever you want to do with tls value ...
	//   })
	//
	GetTLS() interface{}

	// Terminate terminates the given thread gracefully.
	// Scheduled but unexecuted calls will be discarded.
	Terminate()
}

Thread represents a thread instance.

func New

func New() Thread

New creates a new thread instance.