From 113f7abc47a8f1f4f60153d7849e29e028b96fc1 Mon Sep 17 00:00:00 2001 From: TimAndy Date: Mon, 16 Oct 2023 09:35:19 +0800 Subject: [PATCH] Modify readme file --- README.md | 59 +++++++++++++++++++++++++++++++++++++++++++--------- README_zh.md | 59 +++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 98 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d2266ff..df19312 100644 --- a/README.md +++ b/README.md @@ -94,12 +94,19 @@ func main() { 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. + // 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()) + }) + go task.Run() + // Wait for the sub-coroutine to finish executing. time.Sleep(time.Second) } @@ -114,6 +121,8 @@ threadLocal in goroutine: inheritableThreadLocal in goroutine: threadLocal in goroutine by Go: inheritableThreadLocal in goroutine by Go: Hello world2 +threadLocal in task by WrapTask: +inheritableThreadLocal in task by WrapTask: Hello world2 ``` # API @@ -128,31 +137,61 @@ It can be obtained directly through assembly code under `386`, `amd64`, `armv6`, ## `NewThreadLocal() ThreadLocal` -Creates a new `ThreadLocal` instance with a stored default value of `nil`. +Create a new `ThreadLocal` instance with the initial value stored with `nil`. ## `NewThreadLocalWithInitial(supplier Supplier) ThreadLocal` -Creates a new `ThreadLocal` instance with default values stored by calling `supplier()`. +Create a new `ThreadLocal` instance with the initial value stored as the return value of the method `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. +Create a new `ThreadLocal` instance with the initial value stored with `nil`. +When a new coroutine is started via `Go()`, `GoWait()` or `GoWaitResult()`, the value of the current coroutine is copied to the new coroutine. +When a new task is created via `WrapTask()`, `WrapWaitTask()` or `WrapWaitResultTask()`, the value of the current coroutine is captured to the new task. ## `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. +Create a new `ThreadLocal` instance with the initial value stored as the return value of the method `supplier()`. +When a new coroutine is started via `Go()`, `GoWait()` or `GoWaitResult()`, the value of the current coroutine is copied to the new coroutine. +When a new task is created via `WrapTask()`, `WrapWaitTask()` or `WrapWaitResultTask()`, the value of the current coroutine is captured to the new task. + +## `WrapTask(fun Runnable) FutureTask` + +Create a new task and capture the `inheritableThreadLocals` from the current goroutine. +This function returns a `FutureTask` instance, but the return task will not run automatically. +You can run it in a sub-goroutine or goroutine-pool by `FutureTask.Run()` method, wait by `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method. +When the returned task run `panic` will be caught and error stack will be printed, the `panic` will be trigger again when calling `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method. + +## `WrapWaitTask(fun CancelRunnable) FutureTask` + +Create a new task and capture the `inheritableThreadLocals` from the current goroutine. +This function returns a `FutureTask` instance, but the return task will not run automatically. +You can run it in a sub-goroutine or goroutine-pool by `FutureTask.Run()` method, wait by `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method. +When the returned task run `panic` will be caught, the `panic` will be trigger again when calling `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method. + +## `WrapWaitResultTask(fun CancelCallable) FutureTask` + +Create a new task and capture the `inheritableThreadLocals` from the current goroutine. +This function returns a `FutureTask` instance, but the return task will not run automatically. +You can run it in a sub-goroutine or goroutine-pool by `FutureTask.Run()` method, wait and get result by `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method. +When the returned task run `panic` will be caught, the `panic` will be trigger again when calling `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method. ## `Go(fun Runnable)` -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. +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 CancelRunnable) Future` +## `GoWait(fun CancelRunnable) FutureTask` -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 `Future.Get()` or `Future.GetWithTimeout()` method that returns a value. Any `panic` while the child coroutine is executing will be caught and thrown again when `Future.Get()` or `Future.GetWithTimeout()` is called. +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 `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method that returns a value. +Any `panic` while the child coroutine is executing will be caught and thrown again when `FutureTask.Get()` or `FutureTask.GetWithTimeout()` is called. -## `GoWaitResult(fun CancelCallable) Future` +## `GoWaitResult(fun CancelCallable) FutureTask` -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 `Future.Get()` or `Future.GetWithTimeout()` method of the return value. Any `panic` while the child coroutine is executing will be caught and thrown again when `Future.Get()` or `Future.GetWithTimeout()` is called. +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 `FutureTask.Get()` or `FutureTask.GetWithTimeout()` method of the return value. +Any `panic` while the child coroutine is executing will be caught and thrown again when `FutureTask.Get()` or `FutureTask.GetWithTimeout()` is called. [More API Documentation](https://pkg.go.dev/github.com/timandy/routine#section-documentation) diff --git a/README_zh.md b/README_zh.md index e9a1040..4ac7871 100644 --- a/README_zh.md +++ b/README_zh.md @@ -94,12 +94,19 @@ func main() { fmt.Println("inheritableThreadLocal in goroutine:", inheritableThreadLocal.Get()) }() - // 但是,可以通过 Go/GoWait/GoWaitResul 函数启动一个新的子协程,当前协程的所有可继承变量都可以自动传递。 + // 但是,可以通过 Go/GoWait/GoWaitResult 函数启动一个新的子协程,当前协程的所有可继承变量都可以自动传递。 routine.Go(func() { fmt.Println("threadLocal in goroutine by Go:", threadLocal.Get()) fmt.Println("inheritableThreadLocal in goroutine by Go:", inheritableThreadLocal.Get()) }) + // 也可以通过 WrapTask/WrapWaitTask/WrapWaitResultTask 函数创建一个任务,当前协程的所有可继承变量都可以被自动捕获。 + task := routine.WrapTask(func() { + fmt.Println("threadLocal in task by WrapTask:", threadLocal.Get()) + fmt.Println("inheritableThreadLocal in task by WrapTask:", inheritableThreadLocal.Get()) + }) + go task.Run() + // 等待子协程执行完。 time.Sleep(time.Second) } @@ -114,6 +121,8 @@ threadLocal in goroutine: inheritableThreadLocal in goroutine: threadLocal in goroutine by Go: inheritableThreadLocal in goroutine by Go: Hello world2 +threadLocal in task by WrapTask: +inheritableThreadLocal in task by WrapTask: Hello world2 ``` # API文档 @@ -128,31 +137,61 @@ inheritableThreadLocal in goroutine by Go: Hello world2 ## `NewThreadLocal() ThreadLocal` -创建一个新的`ThreadLocal`实例,其存储的默认值为`nil`。 +创建一个新的`ThreadLocal`实例,其存储的初始值为`nil`。 ## `NewThreadLocalWithInitial(supplier Supplier) ThreadLocal` -创建一个新的`ThreadLocal`实例,其存储的默认值会通过调用`supplier()`生成。 +创建一个新的`ThreadLocal`实例,其存储的初始值为方法`supplier()`的返回值。 ## `NewInheritableThreadLocal() ThreadLocal` -创建一个新的`ThreadLocal`实例,其存储的默认值为`nil`。当通过`Go()`、`GoWait()`或`GoWaitResult()`启动新协程时,当前协程的值会被复制到新协程。 +创建一个新的`ThreadLocal`实例,其存储的初始值为`nil`。 +当通过`Go()`、`GoWait()`或`GoWaitResult()`启动新协程时,当前协程的值会被复制到新协程。 +当通过`WrapTask()`、`WrapWaitTask()`或`WrapWaitResultTask()`创建任务时,当前协程的值会被捕获。 ## `NewInheritableThreadLocalWithInitial(supplier Supplier) ThreadLocal` -创建一个新的`ThreadLocal`实例,其存储的默认值会通过调用`supplier()`生成。当通过`Go()`、`GoWait()`或`GoWaitResult()`启动新协程时,当前协程的值会被复制到新协程。 +创建一个新的`ThreadLocal`实例,其存储的初始值为方法`supplier()`的返回值。 +当通过`Go()`、`GoWait()`或`GoWaitResult()`启动新协程时,当前协程的值会被复制到新协程。 +当通过`WrapTask()`、`WrapWaitTask()`或`WrapWaitResultTask()`创建任务时,当前协程的值会被捕获。 + +## `WrapTask(fun Runnable) FutureTask` + +创建一个新任务,并捕获当前协程的`inheritableThreadLocals`。 +此函数返回一个`FutureTask`实例,但返回的任务不会自动运行。 +你可以通过`FutureTask.Run()`方法在子协程或协程池中运行它,通过`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法等待任务执行完毕。 +任务执行时的任何`panic`都会被捕获并打印错误堆栈,在调用`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法时`panic`会被再次抛出。 + +## `WrapWaitTask(fun CancelRunnable) FutureTask` + +创建一个新任务,并捕获当前协程的`inheritableThreadLocals`。 +此函数返回一个`FutureTask`实例,但返回的任务不会自动运行。 +你可以通过`FutureTask.Run()`方法在子协程或协程池中运行它,通过`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法等待任务执行完毕。 +任务执行时的任何`panic`都会被捕获,在调用`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法时`panic`会被再次抛出。 + +## `WrapWaitResultTask(fun CancelCallable) FutureTask` + +创建一个新任务,并捕获当前协程的`inheritableThreadLocals`。 +此函数返回一个`FutureTask`实例,但返回的任务不会自动运行。 +你可以通过`FutureTask.Run()`方法在子协程或协程池中运行它,通过`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法等待任务执行完毕并获取结果。 +任务执行时的任何`panic`都会被捕获,在调用`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法时`panic`会被再次抛出。 ## `Go(fun Runnable)` -启动一个新的协程,同时自动将当前协程的全部上下文`inheritableThreadLocals`数据复制至新协程。子协程执行时的任何`panic`都会被捕获并自动打印堆栈。 +启动一个新的协程,同时自动将当前协程的全部上下文`inheritableThreadLocals`数据复制至新协程。 +子协程执行时的任何`panic`都会被捕获并自动打印堆栈。 -## `GoWait(fun CancelRunnable) Future` +## `GoWait(fun CancelRunnable) FutureTask` -启动一个新的协程,同时自动将当前协程的全部上下文`inheritableThreadLocals`数据复制至新协程。可以通过返回值的`Future.Get()`或`Future.GetWithTimeout()`方法等待子协程执行完毕。子协程执行时的任何`panic`都会被捕获并在调用`Future.Get()`或`Future.GetWithTimeout()`时再次抛出。 +启动一个新的协程,同时自动将当前协程的全部上下文`inheritableThreadLocals`数据复制至新协程。 +可以通过返回值的`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法等待子协程执行完毕。 +子协程执行时的任何`panic`都会被捕获并在调用`FutureTask.Get()`或`FutureTask.GetWithTimeout()`时再次抛出。 -## `GoWaitResult(fun CancelCallable) Future` +## `GoWaitResult(fun CancelCallable) FutureTask` -启动一个新的协程,同时自动将当前协程的全部上下文`inheritableThreadLocals`数据复制至新协程。可以通过返回值的`Future.Get()`或`Future.GetWithTimeout()`方法等待子协程执行完毕并获取返回值。子协程执行时的任何`panic`都会被捕获并在调用`Future.Get()`或`Future.GetWithTimeout()`时再次抛出。 +启动一个新的协程,同时自动将当前协程的全部上下文`inheritableThreadLocals`数据复制至新协程。 +可以通过返回值的`FutureTask.Get()`或`FutureTask.GetWithTimeout()`方法等待子协程执行完毕并获取返回值。 +子协程执行时的任何`panic`都会被捕获并在调用`FutureTask.Get()`或`FutureTask.GetWithTimeout()`时再次抛出。 [更多API文档](https://pkg.go.dev/github.com/timandy/routine#section-documentation)