Skip to content

Commit 8a37a61

Browse files
ghosindghosind
committed
doc: update readme.
1 parent 6148549 commit 8a37a61

File tree

1 file changed

+34
-105
lines changed

1 file changed

+34
-105
lines changed

‎README.md

Lines changed: 34 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -9,137 +9,66 @@
99

1010
English | [简体中文](./README-CN.md)
1111

12-
A tool collection that provided asynchronous workflow control utilities, inspired by [JavaScript `Promise` Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and [Node.js async package](https://caolan.github.io/async/v3/).
12+
It's a powerful asynchronous utility library inspired by [JavaScript `Promise` Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and [Node.js async package](https://caolan.github.io/async/v3/).
1313

1414
## Installation and Requirement
1515

16-
Run the following command to install the library, and this library requires Go 1.18 and later versions.
16+
Run the following command to install this library, and Go 1.18 and later versions required.
1717

1818
```sh
1919
go get -u github.com/ghosind/go-async
2020
```
2121

22-
## Getting Started
23-
24-
### The function to run
22+
And then, import the library into your own code.
2523

26-
The most of utility functions of this library accept any type of function to run, you can set the parameters and the return values as any type and any number of return values that you want. However, for best practice, we recommend you to set the first parameter as `context.Context` to receive the signals and make the type of the last return value as an error to let the utilities know whether an error happened or not.
24+
```go
25+
import "github.com/ghosind/go-async"
26+
```
2727

28-
### Run all functions until they are finished
28+
> This library is not stable yet, anything may change in the later versions.
2929
30-
`All` function can help you to execute all the functions asynchronously. It'll wrap all return values to a two-dimensional `any` type slice and return it if all functions are completed and no error returns or panic.
30+
## Getting Started
3131

32-
If any function returns an error or panics, the `All` function will terminate immediately and return the error. It'll also send a cancel signal to other uncompleted functions by context if they accept a context by their first parameter.
32+
For the following example, it runs the functions concurrently and returns the return values until all functions have been completed.
3333

3434
```go
3535
out, err := async.All(func (ctx context.Context) (int, error) {
3636
return 0, nil
37-
}, func (ctx context.Context) (string, error)) {
37+
}, func () (string, error)) {
38+
time.Sleep(100 * time.Millisecond)
3839
return "hello", nil
39-
}/*, ...*/)
40+
})
4041
// out: [][]any{{0, <nil>}, {"hello", <nil>}}
4142
// err: <nil>
42-
43-
out, err := async.All(func (ctx context.Context) (int, error) {
44-
return 0, nil
45-
}, func (ctx context.Context) (string, error)) {
46-
return "", errors.New("some error")
47-
}/*, ...*/)
48-
// out: [][]any{{}, {"", some error}}
49-
// err: function 1 error: some error
50-
```
51-
52-
If you do not want to terminate the execution when some function returns an error or panic, you can try the `AllCompleted` function. The `AllCompleted` function executes until all functions are finished or panic. It'll return a list of the function return values, and an error to indicate whether any functions return error or panic.
53-
54-
```go
55-
out, err := async.AllCompleted(func (ctx context.Context) (int, error) {
56-
return 0, nil
57-
}, func (ctx context.Context) (string, error) {
58-
return "", errors.New("some error")
59-
}/*, ...*/)
60-
// out: [][]any{{0, <nil>}, {"", some error}}}
61-
// err: function 1 error: some error
6243
```
6344

64-
### Get first output
65-
66-
If you want to run a list of functions and get the output of the first finish function, you can try the `Race` function. The `Race` function will run all functions asynchronously, and return when a function is finished or panicked.
67-
68-
The `Race` function returns three values:
45+
There are over 10 asynchronous control flow functions available, please visit [Go Reference](https://pkg.go.dev/github.com/ghosind/go-async) to see the documentation and examples.
6946

70-
- 1st value: an output list of the first finish function.
71-
- 2nd value: the index of the first finish function.
72-
- 3rd value: the execution error that from the first finish or panic function.
47+
## The function to run
7348

74-
```go
75-
out, index, err := async.Race(func (ctx context.Context) (int, error) {
76-
request.Get("https://example.com")
77-
return 0, nil
78-
}, func (ctx context.Context) (string, error) {
79-
time.Sleep(time.Second)
80-
return "test", nil
81-
})
82-
// If the first function faster than the second one:
83-
// out: []any{0, <nil>}, index: 0, err: <nil>
84-
//
85-
// Otherwise:
86-
// out: []any{"test", <nil>}, index: 1, err: <nil>
87-
```
88-
89-
### Run all functions with concurrency limit
90-
91-
To run all functions asynchronously but with the specified concurrency limitation, you can use the `Parallel` function. The `Parallel` function accepts a number that the concurrency limitation and the list of functions to run. The number of the concurrency limitation must be greater than or equal to 0. The number 0 means no limitation of the concurrency number, and it has the same effect as the `All` function.
92-
93-
```go
94-
// Run 2 functions asynchronously at the time.
95-
out, err := async.Parallel(2, func (ctx context.Context) (int, error) {
96-
// Do something
97-
return 1, nil
98-
}, func (ctx context.Context) (string, error) {
99-
// Do something
100-
return "hello", nil
101-
}, func (ctx context.Context) error {
102-
// Do something
103-
return nil
104-
}/* , ... */)
105-
// out: [][]any{{1, <nil>}, {"hello", <nil>}, {<nil>}}
106-
// err: <nil>
107-
```
108-
109-
The `Parallel` will also be terminated if any function panics or returns an error. If you do not want to terminate the execution of other functions, you can try to use `ParallelCompleted`. The `ParallelCompleted` function will run all functions until all functions are finished. It will return the output list and an error to indicate whether any function errored.
49+
The most of utility functions of this library accept any type of function to run, you can set the parameters and the return values as any type and any number of return values that you want. However, for best practice, we recommend you to set the first parameter as `context.Context` to receive the signals and make the type of the last return value as an error to let the utilities know whether an error happened or not.
11050

111-
### Run a function forever until it returns an error or panic
51+
## Customize context
11252

113-
For `Forever` function, you can use it to run a function forever until it returns an error or panics. You need to run the `Forever` function with a `ForeverFn` type function, and you can see more information about `ForeverFn` after the following example.
53+
For all functions, you can use the `XXXWithContext` function (like `AllWithContext`, `RaceWithContext`, ...) to set the context by yourself.
11454

115-
```go
116-
err := Forever(func(ctx context.Context, next func(context.Context)) error {
117-
v := ctx.Value("key")
118-
if v != nil {
119-
vi := v.(int)
120-
if vi == 5 {
121-
return errors.New("finish")
122-
}
123-
124-
fmt.Printf("value: %d\n", vi)
125-
126-
next(context.WithValue(ctx, "key", vi+1))
127-
} else {
128-
next(context.WithValue(ctx, "key", 1))
129-
}
130-
131-
return nil
132-
})
133-
fmt.Printf("err: %v\n", err)
134-
// value: 1
135-
// value: 2
136-
// value: 3
137-
// value: 4
138-
// err: finish
139-
```
55+
## Available Utility Functions
14056

141-
The `ForeverFn` accepts two parameters, the first one is a context from the caller or the last invocation. The second parameter of `ForeverFn` is a function to set the context that passes to the next invocation. For `ForeverFn`, it is an optional behavior to call the `next` function, and only the first invoke will work.
57+
- [`All`](https://pkg.go.dev/github.com/ghosind/go-async#All)
58+
- [`AllCompleted`](https://pkg.go.dev/github.com/ghosind/go-async#AllCompleted)
59+
- [`Forever`](https://pkg.go.dev/github.com/ghosind/go-async#Forever)
60+
- [`Parallel`](https://pkg.go.dev/github.com/ghosind/go-async#Parallel)
61+
- [`ParallelCompleted`](https://pkg.go.dev/github.com/ghosind/go-async#ParallelCompleted)
62+
- [`Race`](https://pkg.go.dev/github.com/ghosind/go-async#Race)
63+
- [`Retry`](https://pkg.go.dev/github.com/ghosind/go-async#Retry)
64+
- [`Seq`](https://pkg.go.dev/github.com/ghosind/go-async#Seq)
65+
- [`Series`](https://pkg.go.dev/github.com/ghosind/go-async#Series)
66+
- [`Times`](https://pkg.go.dev/github.com/ghosind/go-async#Times)
67+
- [`TimesLimit`](https://pkg.go.dev/github.com/ghosind/go-async#TimesLimit)
68+
- [`TimesSeries`](https://pkg.go.dev/github.com/ghosind/go-async#TimesSeries)
69+
- [`Until`](https://pkg.go.dev/github.com/ghosind/go-async#Until)
70+
- [`While`](https://pkg.go.dev/github.com/ghosind/go-async#While)
14271

143-
### Customize context
72+
## License
14473

145-
For all utility functions, you can use the `XXXWithContext` function (like `AllWithContext`, `RaceWithContext`, ...) to set the context by yourself.
74+
The library published under MIT License, please see license file for more details.

0 commit comments

Comments
 (0)