routine

README

routine

中文版

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

Introduce

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

If you have used other languages such as C++, Java and so on, then you must be familiar with ThreadLocal, but after starting to use Golang, you will be deeply confused and distressed by the lack of convenient functions like ThreadLocal.

Of course, you can choose to use Context, 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 of routine is to open up another way: Introduce goroutine local storage to the Golang world.

Usage & Demo

This chapter briefly introduces how to install and use the routine library.

Install

go get github.com/timandy/routine

Use goid

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

package main

import (
	"fmt"
	"github.com/timandy/routine"
	"time"
)

func main() {
	goid := routine.Goid()
	fmt.Printf("cur goid: %v\n", goid)
	go func() {
		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, the main function starts a new coroutine, so Goid() returns the main coroutine 1 and the child coroutine 6:

cur goid: 1
sub goid: 6

Use ThreadLocal

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

package main

import (
	"fmt"
	"github.com/timandy/routine"
	"time"
)

var threadLocal = routine.NewThreadLocal()
var inheritableThreadLocal = routine.NewInheritableThreadLocal()

func main() {
	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".
	go func() {
		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/GoWaitResul 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())
	})

	// Wait for the sub-coroutine to finish executing.
	time.Sleep(time.Second)
}

The execution result is:

threadLocal: hello world
inheritableThreadLocal: Hello world2
threadLocal in goroutine: <nil>
inheritableThreadLocal in goroutine: <nil>
threadLocal in goroutine by Go: <nil>
inheritableThreadLocal in goroutine by Go: Hello world2

API

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

Goid() int64

Get the goid of the current goroutine.

It can be obtained directly through assembly code under 386, amd64, armv6, armv7, arm64 architectures. This operation has extremely high performance and the time-consuming is usually only one-fifth of rand.Int().

NewThreadLocal() ThreadLocal

Creates a new ThreadLocal instance with a stored default value of nil.

NewThreadLocalWithInitial(supplier Supplier) ThreadLocal

Creates a new ThreadLocal instance with default values stored by calling supplier().

NewInheritableThreadLocal() ThreadLocal

Creates a new ThreadLocal instance with a stored default value of nil. When a new coroutine is started via Go(), GoWait() or GoWaitResult(), the value of the current coroutine is copied to the new coroutine.

NewInheritableThreadLocalWithInitial(supplier Supplier) ThreadLocal

Creates a new ThreadLocal instance with stored default values generated by calling supplier(). When a new coroutine is started via Go(), GoWait() or GoWaitResult(), the value of the current coroutine is copied to the new coroutine.

Go(fun func())

Start a new coroutine and automatically copy all contextual inheritableThreadLocals data of the current coroutine to the new coroutine. Any panic while the child coroutine is executing will be caught and the stack automatically printed.

GoWait(fun func()) Feature

Start a new coroutine and automatically copy all contextual inheritableThreadLocals data of the current coroutine to the new coroutine. You can wait for the sub-coroutine to finish executing through the Feature.Get() method that returns a value. Any panic while the child coroutine is executing will be caught and thrown again when Feature.Get() is called.

GoWaitResult(fun func() Any) Feature

Start a new coroutine and automatically copy all contextual inheritableThreadLocals 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 the Feature.Get() method of the return value. Any panic while the child coroutine is executing will be caught and thrown again when Feature.Get() is called.

More API Documentation

Garbage Collection

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

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

When the coroutine finishes executing and exits, g.labels will be set to nil, no longer referencing the thread structure.

The thread structure will be collected at the next GC.

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

Support Grid

	darwin	linux	windows
386		✅	✅	386
amd64	✅	✅	✅	amd64
armv6		✅		armv6
armv7		✅		armv7
arm64		✅		arm64
	darwin	linux	windows

✅: Supported

Thanks

routine is forked from go-eden/routine, thanks to the original author for his contribution!

License

routine is released under the Apache License 2.0.

Copyright 2021-2022 TimAndy

Licensed 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.0

Unless required by applicable law or agreed to in writing, software
distributed 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 and
limitations under the License.

Documentation

Index

• func Go(fun Runnable)
• func Goid() int64
• type Any
• type Callable
• type Cloneable
• type Feature
  • func GoWait(fun Runnable) Feature
  • func GoWaitResult(fun Callable) Feature
  • func NewFeature() Feature
• type Runnable
• type RuntimeError
  • func NewRuntimeError(cause Any) RuntimeError
  • func NewRuntimeErrorWithMessage(message string) RuntimeError
  • func NewRuntimeErrorWithMessageCause(message string, cause Any) RuntimeError
• type Supplier
• type ThreadLocal
  • func NewInheritableThreadLocal() ThreadLocal
  • func NewInheritableThreadLocalWithInitial(supplier Supplier) ThreadLocal
  • func NewThreadLocal() ThreadLocal
  • func NewThreadLocalWithInitial(supplier Supplier) ThreadLocal

Functions

func Go

func Go(fun Runnable)

Go starts a new goroutine, and copy inheritableThreadLocals from current goroutine. This function will auto invoke the fun and print error stack when panic occur in goroutine.

func Goid

func Goid() int64

Goid return the current goroutine's unique id.

Types

type Any

type Any = interface{}

Any is an alias for interface{} and is equivalent to interface{} in all ways.

type Callable

type Callable func() Any

Callable provides a function that returns a value of type Any.

type Cloneable

type Cloneable interface {
	// Clone create and returns a copy of this object.
	Clone() Any
}

Cloneable interface to support copy itself.

type Feature

type Feature interface {
	// Complete notifies the parent coroutine that the task has completed and returns the execution result.
	// This method is called by the child coroutine.
	Complete(result Any)

	// CompleteError notifies the parent coroutine that the task is terminated due to panic and returns stack information.
	// This method is called by the child coroutine.
	CompleteError(error Any)

	// Get the execution result of the sub-coroutine, if there is no result, return nil.
	// If panic is raised during the execution of the sub-coroutine, it will be raised again at this time.
	// this method is called by the parent coroutine.
	Get() Any
}

Feature provide a way to wait for the sub-coroutine to finish executing, get the return value of the sub-coroutine, and catch the sub-coroutine panic.

func GoWait

func GoWait(fun Runnable) Feature

GoWait starts a new goroutine, and copy inheritableThreadLocals from current goroutine. This function return a Feature pointer, so we can wait by Feature.Get method. If panic occur in goroutine, The panic will be trigger again when calling Feature.Get method.

func GoWaitResult

func GoWaitResult(fun Callable) Feature

GoWaitResult starts a new goroutine, and copy inheritableThreadLocals from current goroutine. This function return a Feature pointer, so we can wait and get result by Feature.Get method. If panic occur in goroutine, The panic will be trigger again when calling Feature.Get method.

func NewFeature

func NewFeature() Feature

NewFeature Create a new instance.

type Runnable

type Runnable func()

Runnable provides a function without return values.

type RuntimeError

type RuntimeError interface {
	// Goid returns the goid of the coroutine that created the current error.
	Goid() int64

	// Gopc returns the pc of go statement that created the current error coroutine.
	Gopc() uintptr

	// Message returns the detail message string of this error.
	Message() string

	// StackTrace returns an array of stack trace elements, each representing one stack frame.
	StackTrace() []uintptr

	// Cause returns the cause of this error or nil if the cause is nonexistent or unknown.
	Cause() RuntimeError

	// Error returns a short description of this error.
	Error() string
}

RuntimeError runtime error with stack info.

func NewRuntimeError

func NewRuntimeError(cause Any) RuntimeError

NewRuntimeError create a new RuntimeError instance.

func NewRuntimeErrorWithMessage

func NewRuntimeErrorWithMessage(message string) RuntimeError

NewRuntimeErrorWithMessage create a new RuntimeError instance.

func NewRuntimeErrorWithMessageCause

func NewRuntimeErrorWithMessageCause(message string, cause Any) RuntimeError

NewRuntimeErrorWithMessageCause create a new RuntimeError instance.

type Supplier

type Supplier func() Any

Supplier provides a function that returns a value of type Any.

type ThreadLocal

type ThreadLocal interface {
	// Get returns the value in the current goroutine's local threadLocals or inheritableThreadLocals, if it was set before.
	Get() Any

	// Set copy the value into the current goroutine's local threadLocals or inheritableThreadLocals.
	Set(value Any)

	// Remove delete the value from the current goroutine's local threadLocals or inheritableThreadLocals.
	Remove()
}

ThreadLocal provides goroutine-local variables.

func NewInheritableThreadLocal

func NewInheritableThreadLocal() ThreadLocal

NewInheritableThreadLocal create and return a new ThreadLocal instance. The initial value is nil. The value can be inherited to sub goroutines witch started by Go, GoWait, GoWaitResult methods.

func NewInheritableThreadLocalWithInitial

func NewInheritableThreadLocalWithInitial(supplier Supplier) ThreadLocal

NewInheritableThreadLocalWithInitial create and return a new ThreadLocal instance. The initial value is determined by invoking the supplier method. The value can be inherited to sub goroutines witch started by Go, GoWait, GoWaitResult methods.

func NewThreadLocal

func NewThreadLocal() ThreadLocal

NewThreadLocal create and return a new ThreadLocal instance. The initial value is nil.

func NewThreadLocalWithInitial

func NewThreadLocalWithInitial(supplier Supplier) ThreadLocal

NewThreadLocalWithInitial create and return a new ThreadLocal instance. The initial value is determined by invoking the supplier method.