Repository files navigation

中文版

routine encapsulates and provides some easy-to-use, non-competitive, high-performancegoroutine context access interfaces, which can help you access coroutine context information more gracefully.

From the very beginning of its design, theGolang language has spared no effort to shield the concept of coroutine context from developers, including the acquisition of coroutinegoid, the state of coroutine within the process, and the storage of coroutine context.

If you have used other languages such asC++,Java and so on, then you must be familiar withThreadLocal, but after starting to useGolang, you will be deeply confused and distressed by the lack of convenient functions likeThreadLocal.

Of course, you can choose to useContext, which carries all the context information, appears in the first input parameter of all functions, and then shuttles around your system.

And the core goal ofroutine is to open up another way: Introducegoroutine local storage to theGolang world.

🔥Version1.1.5 introduces a new static mode.

• 🚀Performance improved by over20%.

• 🚀Memory access is now safer.

• ❗The compile command requires additional parameters-a -toolexec='routinex -v'.

For more details, visit:RoutineX Compiler

This chapter briefly introduces how to install and use theroutine library.

go get github.com/timandy/routine

The following code simply demonstrates the use ofroutine.Goid():

package mainimport ("fmt""time""github.com/timandy/routine")funcmain() {goid:=routine.Goid()fmt.Printf("cur goid: %v\n",goid)gofunc() {goid:=routine.Goid()fmt.Printf("sub goid: %v\n",goid)}()// Wait for the sub-coroutine to finish executing.time.Sleep(time.Second)}

In this example, themain function starts a new coroutine, soGoid() returns the main coroutine1 and the child coroutine6:

cur goid: 1sub goid: 6

The following code briefly demonstratesThreadLocal's creation, setting, getting, spreading across coroutines, etc.:

package mainimport ("fmt""time""github.com/timandy/routine")varthreadLocal=routine.NewThreadLocal[string]()varinheritableThreadLocal=routine.NewInheritableThreadLocal[string]()funcmain() {threadLocal.Set("hello world")inheritableThreadLocal.Set("Hello world2")fmt.Println("threadLocal:",threadLocal.Get())fmt.Println("inheritableThreadLocal:",inheritableThreadLocal.Get())// The child coroutine cannot read the previously assigned "hello world".gofunc() {fmt.Println("threadLocal in goroutine:",threadLocal.Get())fmt.Println("inheritableThreadLocal in goroutine:",inheritableThreadLocal.Get())}()// However, a new sub-coroutine can be started via the Go/GoWait/GoWaitResult function, and all inheritable variables of the current coroutine can be passed automatically.routine.Go(func() {fmt.Println("threadLocal in goroutine by Go:",threadLocal.Get())fmt.Println("inheritableThreadLocal in goroutine by Go:",inheritableThreadLocal.Get())})// You can also create a task via the WrapTask/WrapWaitTask/WrapWaitResultTask function, and all inheritable variables of the current coroutine can be automatically captured.task:=routine.WrapTask(func() {fmt.Println("threadLocal in task by WrapTask:",threadLocal.Get())fmt.Println("inheritableThreadLocal in task by WrapTask:",inheritableThreadLocal.Get())})gotask.Run()// Wait for the sub-coroutine to finish executing.time.Sleep(time.Second)}

The execution result is:

threadLocal: hello worldinheritableThreadLocal: Hello world2threadLocal in goroutine:inheritableThreadLocal in goroutine:threadLocal in goroutine by Go:inheritableThreadLocal in goroutine by Go: Hello world2threadLocal in task by WrapTask:inheritableThreadLocal in task by WrapTask: Hello world2

This chapter introduces in detail all the interfaces encapsulated by theroutine library, as well as their core functions and implementation methods.

Get thegoid of the currentgoroutine.

It can be obtained directly through assembly code under386,amd64,armv6,armv7,arm64,loong64,mips,mipsle,mips64,mips64le,ppc64,ppc64le,riscv64,s390x,wasm architectures. This operation has extremely high performance and the time-consuming is usually only one-fifth ofrand.Int().

Create a newThreadLocal[T] instance with the initial value stored with the default value of typeT.

Create a newThreadLocal[T] instance with the initial value stored as the return value of the methodsupplier().

Create a newThreadLocal[T] instance with the initial value stored with the default value of typeT.When a new coroutine is started viaGo(),GoWait() orGoWaitResult(), the value of the current coroutine is copied to the new coroutine.When a new task is created viaWrapTask(),WrapWaitTask() orWrapWaitResultTask(), the value of the current coroutine is captured to the new task.

Create a newThreadLocal[T] instance with the initial value stored as the return value of the methodsupplier().When a new coroutine is started viaGo(),GoWait() orGoWaitResult(), the value of the current coroutine is copied to the new coroutine.When a new task is created viaWrapTask(),WrapWaitTask() orWrapWaitResultTask(), the value of the current coroutine is captured to the new task.

Create a new task and capture theinheritableThreadLocals from the current goroutine.This function returns aFutureTask instance, but the return task will not run automatically.You can run it in a sub-goroutine or goroutine-pool byFutureTask.Run() method, wait byFutureTask.Get() orFutureTask.GetWithTimeout() method.When the returned task runpanic will be caught and error stack will be printed, thepanic will be trigger again when callingFutureTask.Get() orFutureTask.GetWithTimeout() method.

Create a new task and capture theinheritableThreadLocals from the current goroutine.This function returns aFutureTask instance, but the return task will not run automatically.You can run it in a sub-goroutine or goroutine-pool byFutureTask.Run() method, wait byFutureTask.Get() orFutureTask.GetWithTimeout() method.When the returned task runpanic will be caught, thepanic will be trigger again when callingFutureTask.Get() orFutureTask.GetWithTimeout() method.

Create a new task and capture theinheritableThreadLocals from the current goroutine.This function returns aFutureTask instance, but the return task will not run automatically.You can run it in a sub-goroutine or goroutine-pool byFutureTask.Run() method, wait and get result byFutureTask.Get() orFutureTask.GetWithTimeout() method.When the returned task runpanic will be caught, thepanic will be trigger again when callingFutureTask.Get() orFutureTask.GetWithTimeout() method.

Start a new coroutine and automatically copy all contextualinheritableThreadLocals data of the current coroutine to the new coroutine.Anypanic while the child coroutine is executing will be caught and the stack automatically printed.

Start a new coroutine and automatically copy all contextualinheritableThreadLocals data of the current coroutine to the new coroutine.You can wait for the sub-coroutine to finish executing through theFutureTask.Get() orFutureTask.GetWithTimeout() method that returns a value.Anypanic while the child coroutine is executing will be caught and thrown again whenFutureTask.Get() orFutureTask.GetWithTimeout() is called.

Start a new coroutine and automatically copy all contextualinheritableThreadLocals data of the current coroutine to the new coroutine.You can wait for the sub-coroutine to finish executing and get the return value through theFutureTask.Get() orFutureTask.GetWithTimeout() method of the return value.Anypanic while the child coroutine is executing will be caught and thrown again whenFutureTask.Get() orFutureTask.GetWithTimeout() is called.

More API Documentation

routine allocates athread structure for each coroutine, which stores context variable information related to the coroutine.

A pointer to this structure is stored on theg.labels field of the coroutine structure.

When the coroutine finishes executing and exits,g.labels will be set tonil, no longer referencing thethread structure.

Thethread structure will be collected at the nextGC.

If the data stored inthread is not additionally referenced, these data will be collected together.

✅: Supported

Thanks to allcontributors for their contributions!

routine is released under theApache License 2.0.

Copyright 2021-2025 TimAndyLicensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at    https://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.