generated from devnw/oss-template
-
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
ci(docs.yml,docs.go): move package docs to dedicated file, exclude fr…
…om lint, and fix action
- Loading branch information
1 parent
6084d17
commit 463386c
Showing
5 changed files
with
208 additions
and
40 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,39 +1,166 @@ | ||
| # Stream is a generic implementation for concurrency communication patterns | ||
| # stream | ||
|
|
||
| [](https://github.com/devnw/stream/actions) | ||
| [](https://goreportcard.com/report/go.atomizer.io/stream) | ||
| [](https://codecov.io/gh/devnw/stream) | ||
| [](https://pkg.go.dev/go.atomizer.io/stream) | ||
| [](https://opensource.org/licenses/Apache-2.0) | ||
| [](http://makeapullrequest.com) | ||
|
|
||
| Stream provides a set of generic functions for working concurrent | ||
| Package stream provides a set of generic functions for working concurrent | ||
| design patterns in Go. | ||
|
|
||
| [)]([https://github.com/devnw/stream/actions](https://github.com/devnw/stream/actions)) | ||
| [)]([https://goreportcard.com/report/go.atomizer.io/stream](https://goreportcard.com/report/go.atomizer.io/stream)) | ||
| [)]([https://codecov.io/gh/devnw/stream](https://codecov.io/gh/devnw/stream)) | ||
| [)]([https://pkg.go.dev/go.atomizer.io/stream](https://pkg.go.dev/go.atomizer.io/stream)) | ||
| [)]([https://opensource.org/licenses/Apache-2.0](https://opensource.org/licenses/Apache-2.0)) | ||
| [)]([http://makeapullrequest.com](http://makeapullrequest.com)) | ||
|
|
||
| ## Installation | ||
|
|
||
| To install the package, run: | ||
|
|
||
| ```bash | ||
| go get -u go.atomizer.io/stream@latest | ||
| ```go | ||
| go get -u go.atomizer.io/stream@latest | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| ```go | ||
| import "go.atomizer.io/stream" | ||
| import "go.atomizer.io/stream" | ||
| ``` | ||
|
|
||
| ## Benchmarks | ||
|
|
||
| To execute the benchmarks, run the following command: | ||
|
|
||
| ```bash | ||
| go test -bench=. ./... | ||
| ```go | ||
| go test -bench=. . ./... | ||
| ``` | ||
|
|
||
| To view benchmarks over time for the `main` branch of the repository they can | ||
| be seen on our [Benchmark Report Card]. | ||
|
|
||
| [Benchmark Report Card]: https://devnw.github.io/stream/dev/bench/ | ||
| [Benchmark Report Card]: [https://devnw.github.io/stream/dev/bench/](https://devnw.github.io/stream/dev/bench/) | ||
|
|
||
| ## Variables | ||
|
|
||
| ```golang | ||
| var ErrFnRequired = fmt.Errorf("nil InterceptFunc, Fn is required") | ||
| ``` | ||
|
|
||
| ## Functions | ||
|
|
||
| ### func [Any](/stream.go#L278) | ||
|
|
||
| `func Any[T any](ctx context.Context, in <-chan T) <-chan any` | ||
|
|
||
| Any accepts an incoming data channel and converts the channel to a readonly | ||
| channel of the `any` type. | ||
|
|
||
| ### func [Distribute](/stream.go#L222) | ||
|
|
||
| `func Distribute[T any]( | ||
| ctx context.Context, in <-chan T, out ...chan<- T, | ||
| )` | ||
|
|
||
| Distribute accepts an incoming data channel and distributes the data among | ||
| the supplied outgoing data channels using a dynamic select statement. | ||
|
|
||
| NOTE: Execute the Distribute function in a goroutine if parallel execution is | ||
| desired. Canceling the context or closing the incoming channel is important | ||
| to ensure that the goroutine is properly terminated. | ||
|
|
||
| ### func [Drain](/stream.go#L259) | ||
|
|
||
| `func Drain[T any](ctx context.Context, in <-chan T)` | ||
|
|
||
| Drain accepts a channel and drains the channel until the channel is closed | ||
| or the context is canceled. | ||
|
|
||
| ### func [FanIn](/stream.go#L127) | ||
|
|
||
| `func FanIn[T any](ctx context.Context, in ...<-chan T) <-chan T` | ||
|
|
||
| FanIn accepts incoming data channels and forwards returns a single channel | ||
| that receives all the data from the supplied channels. | ||
|
|
||
| NOTE: The transfer takes place in a goroutine for each channel | ||
| so ensuring that the context is canceled or the incoming channels | ||
| are closed is important to ensure that the goroutine is terminated. | ||
|
|
||
| ### func [FanOut](/stream.go#L162) | ||
|
|
||
| `func FanOut[T any]( | ||
| ctx context.Context, in <-chan T, out ...chan<- T, | ||
| )` | ||
|
|
||
| FanOut accepts an incoming data channel and copies the data to each of the | ||
| supplied outgoing data channels. | ||
|
|
||
| NOTE: Execute the FanOut function in a goroutine if parallel execution is | ||
| desired. Canceling the context or closing the incoming channel is important | ||
| to ensure that the goroutine is properly terminated. | ||
|
|
||
| ### func [Intercept](/stream.go#L77) | ||
|
|
||
| `func Intercept[T, U any]( | ||
| ctx context.Context, | ||
| in <-chan T, | ||
| fn InterceptFunc[T, U], | ||
| ) <-chan U` | ||
|
|
||
| Intercept accepts an incoming data channel and a function literal that | ||
| accepts the incoming data and returns data of the same type and a boolean | ||
| indicating whether the data should be forwarded to the output channel. | ||
| The function is executed for each data item in the incoming channel as long | ||
| as the context is not canceled or the incoming channel remains open. | ||
|
|
||
| ### func [Pipe](/stream.go#L47) | ||
|
|
||
| `func Pipe[T any]( | ||
| ctx context.Context, in <-chan T, out chan<- T, | ||
| )` | ||
|
|
||
| Pipe accepts an incoming data channel and pipes it to the supplied | ||
| outgoing data channel. | ||
|
|
||
| NOTE: Execute the Pipe function in a goroutine if parallel execution is | ||
| desired. Canceling the context or closing the incoming channel is important | ||
| to ensure that the goroutine is properly terminated. | ||
|
|
||
| ## Types | ||
|
|
||
| ### type [DurationScaler](/scaler.go#L220) | ||
|
|
||
| `type DurationScaler struct { ... }` | ||
|
|
||
| DurationScaler is used to modify the time.Duration of a ticker or timer based on | ||
| a configured step value and modifier (between -1 and 1) value. | ||
|
|
||
| ### type [InterceptFunc](/stream.go#L70) | ||
|
|
||
| `type InterceptFunc[T, U any] func(context.Context, T) (U, bool)` | ||
|
|
||
| ### type [Scaler](/scaler.go#L34) | ||
|
|
||
| `type Scaler[T, U any] struct { ... }` | ||
|
|
||
| Scaler implements generic auto-scaling logic which starts with a net-zero | ||
| set of processing routines (with the exception of the channel listener) and | ||
| then scales up and down based on the CPU contention of a system and the speed | ||
| at which the InterceptionFunc is able to process data. Once the incoming | ||
| channel becomes blocked (due to nothing being sent) each of the spawned | ||
| routines will finish out their execution of Fn and then the internal timer | ||
| will collapse brining the routine count back to zero until there is more to | ||
| be done. | ||
|
|
||
| To use Scalar, simply create a new Scaler[T, U], configuring the Wait, Life, | ||
| and InterceptFunc fields. These fields are what configure the functionality | ||
| of the Scaler. | ||
|
|
||
| NOTE: Fn is REQUIRED! | ||
|
|
||
| After creating the Scaler instance and configuring it, call the Exec method | ||
| passing the appropriate context and input channel. | ||
|
|
||
| Internally the Scaler implementation will wait for data on the incoming | ||
| channel and attempt to send it to a layer2 channel. If the layer2 channel | ||
| is blocking and the Wait time has been reached, then the Scaler will spawn | ||
| a new layer2 which will increase throughput for the Scaler, and Scaler | ||
| will attempt to send the data to the layer2 channel once more. This process | ||
| will repeat until a successful send occurs. (This should only loop twice). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| // Package stream provides a set of generic functions for working concurrent | ||
| // design patterns in Go. | ||
| // | ||
| // [](https://github.com/devnw/stream/actions) | ||
| // [](https://goreportcard.com/report/go.atomizer.io/stream) | ||
| // [](https://codecov.io/gh/devnw/stream) | ||
| // [](https://pkg.go.dev/go.atomizer.io/stream) | ||
| // [](https://opensource.org/licenses/Apache-2.0) | ||
| // [](http://makeapullrequest.com) | ||
| // | ||
| // ## Installation | ||
| // | ||
| // To install the package, run: | ||
| // | ||
| // go get -u go.atomizer.io/stream@latest | ||
| // | ||
| // ## Usage | ||
| // | ||
| // import "go.atomizer.io/stream" | ||
| // | ||
| // ## Benchmarks | ||
| // | ||
| // To execute the benchmarks, run the following command: | ||
| // | ||
| // go test -bench=. ./... | ||
| // | ||
| // To view benchmarks over time for the `main` branch of the repository they can | ||
| // be seen on our [Benchmark Report Card]. | ||
| // | ||
| // [Benchmark Report Card]: https://devnw.github.io/stream/dev/bench/ | ||
| package stream |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters