Skip to content

Commit

Permalink
docs: autoupdate
Browse files Browse the repository at this point in the history
  • Loading branch information
@MarvinJWendt
MarvinJWendt committed Nov 27, 2023
1 parent 5b06482 commit 3405ef6
Showing 1 changed file with 224 additions and 44 deletions.
268 changes: 224 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,38 @@
<h1 align="center">AtomicGo | template</h1>
<h1 align="center">AtomicGo | pool</h1>

<p align="center">
<img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fatomicgo.dev%2Fapi%2Fshields%2Ftemplate&style=flat-square" alt="Downloads">
<img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fatomicgo.dev%2Fapi%2Fshields%2Fpool&style=flat-square" alt="Downloads">

<a href="https://github.com/atomicgo/template/releases">
<img src="https://img.shields.io/github/v/release/atomicgo/template?style=flat-square" alt="Latest Release">
<a href="https://github.com/atomicgo/pool/releases">
<img src="https://img.shields.io/github/v/release/atomicgo/pool?style=flat-square" alt="Latest Release">
</a>

<a href="https://codecov.io/gh/atomicgo/template" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/atomicgo/template/go.yml?style=flat-square" alt="Tests">
<a href="https://codecov.io/gh/atomicgo/pool" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/atomicgo/pool/go.yml?style=flat-square" alt="Tests">
</a>

<a href="https://codecov.io/gh/atomicgo/template" target="_blank">
<img src="https://img.shields.io/codecov/c/gh/atomicgo/template?color=magenta&logo=codecov&style=flat-square" alt="Coverage">
<a href="https://codecov.io/gh/atomicgo/pool" target="_blank">
<img src="https://img.shields.io/codecov/c/gh/atomicgo/pool?color=magenta&logo=codecov&style=flat-square" alt="Coverage">
</a>

<a href="https://codecov.io/gh/atomicgo/template">
<!-- unittestcount:start --><img src="https://img.shields.io/badge/Unit_Tests-3-magenta?style=flat-square" alt="Unit test count"><!-- unittestcount:end -->
<a href="https://codecov.io/gh/atomicgo/pool">
<!-- unittestcount:start --><img src="https://img.shields.io/badge/Unit_Tests-0-magenta?style=flat-square" alt="Unit test count"><!-- unittestcount:end -->
</a>

<a href="https://opensource.org/licenses/MIT" target="_blank">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT">
</a>

<a href="https://goreportcard.com/report/github.com/atomicgo/template" target="_blank">
<img src="https://goreportcard.com/badge/github.com/atomicgo/template?style=flat-square" alt="Go report">
<a href="https://goreportcard.com/report/github.com/atomicgo/pool" target="_blank">
<img src="https://goreportcard.com/badge/github.com/atomicgo/pool?style=flat-square" alt="Go report">
</a>

</p>

---

<p align="center">
<strong><a href="https://pkg.go.dev/atomicgo.dev/template#section-documentation" target="_blank">Documentation</a></strong>
<strong><a href="https://pkg.go.dev/atomicgo.dev/pool#section-documentation" target="_blank">Documentation</a></strong>
|
<strong><a href="https://github.com/atomicgo/atomicgo/blob/main/CONTRIBUTING.md" target="_blank">Contributing</a></strong>
|
Expand All @@ -51,7 +51,7 @@
</tbody>
</table>
</p>
<h3 align="center"><pre>go get atomicgo.dev/template</pre></h3>
<h3 align="center"><pre>go get atomicgo.dev/pool</pre></h3>
<p align="center">
<table>
<tbody>
Expand All @@ -63,19 +63,59 @@

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# template
# pool

```go
import "atomicgo.dev/template"
import "atomicgo.dev/pool"
```

Package template is used to generate new AtomicGo repositories.
Package pool provides a generic and concurrent worker pool implementation. It allows you to enqueue tasks and process them using a fixed number of workers.

Write the description of the module here. You can use \*\*markdown\*\*\! This description should clearly explain what the package does.
<details><summary>Example (Demo)</summary>
<p>

Example description: https://golang.org/src/encoding/gob/doc.go

<details><summary>Example (Demo)</summary>

```go
package main

import (
"atomicgo.dev/pool"
"context"
"log"
"time"
)

func main() {
// Create a new pool with 3 workers
p := pool.New[int](pool.Config{
MaxWorkers: 3,
})

// Set the task handler to process integers, simulating a 1-second task
p.SetHandler(func(ctx context.Context, i int) error {
log.Printf("Processing %d", i)
time.Sleep(time.Second)
return nil
})

// Start the pool
p.Start()

// Add 10 tasks to the pool
for i := 0; i < 10; i++ {
p.Add(i)
}

// Close the pool and wait for all tasks to complete
p.Close()
}
```

</p>
</details>

<details><summary>Example (Error Handling)</summary>
<p>


Expand All @@ -84,64 +124,204 @@ Example description: https://golang.org/src/encoding/gob/doc.go
package main

import (
"atomicgo.dev/template"
"atomicgo.dev/pool"
"context"
"fmt"
"log"
)

func main() {
fmt.Println(template.HelloWorld())
// Create a new pool
p := pool.New[int](pool.Config{
MaxWorkers: 2,
})

// Set the task handler, which returns an error for even numbers
p.SetHandler(func(ctx context.Context, i int) error {
if i%2 == 0 {
return fmt.Errorf("error processing %d", i)
}

log.Printf("Successfully processed %d", i)

return nil
})

// Set a custom error handler that logs errors
p.SetErrorHandler(func(err error, pool *pool.Pool[int]) {
log.Printf("Encountered an error: %v", err)
// Optional: you can call pool.Kill() here if you want to stop the whole pool on the first error
})

// Start the pool
p.Start()

// Add 5 tasks to the pool
for i := 0; i < 5; i++ {
p.Add(i)
}

// Close the pool and wait for all tasks to complete
p.Close()
}
```

#### Output
</p>
</details>

<details><summary>Example (Timeout)</summary>
<p>

```
Hello, World!


```go
package main

import (
"atomicgo.dev/pool"
"context"
"log"
"time"
)

func main() {
// Create a new pool with a short timeout of 2 seconds
p := pool.New[int](pool.Config{
MaxWorkers: 3,
Timeout: time.Second * 2,
})

// Set the task handler with a task that may exceed the timeout
p.SetHandler(func(ctx context.Context, i int) error {
log.Printf("Processing %d", i)
time.Sleep(time.Second * 3) // This sleep is longer than the timeout
return nil
})

// Start the pool
p.Start()

// Add tasks to the pool
for i := 0; i < 5; i++ {
p.Add(i)
}

// Close the pool and wait for all tasks to complete
p.Close()
}
```

</p>
</details>

## Index

- [func HelloWorld\(\) string](<#HelloWorld>)
- [type Config](<#Config>)
- [type ErrorHandler](<#ErrorHandler>)
- [type Pool](<#Pool>)
- [func New\[T any\]\(config Config\) \*Pool\[T\]](<#New>)
- [func \(p \*Pool\[T\]\) Add\(item T\)](<#Pool[T].Add>)
- [func \(p \*Pool\[T\]\) Close\(\)](<#Pool[T].Close>)
- [func \(p \*Pool\[T\]\) Kill\(\)](<#Pool[T].Kill>)
- [func \(p \*Pool\[T\]\) SetErrorHandler\(handler ErrorHandler\[T\]\) \*Pool\[T\]](<#Pool[T].SetErrorHandler>)
- [func \(p \*Pool\[T\]\) SetHandler\(handler func\(context.Context, T\) error\) \*Pool\[T\]](<#Pool[T].SetHandler>)
- [func \(p \*Pool\[T\]\) Start\(\)](<#Pool[T].Start>)


<a name="HelloWorld"></a>
## func [HelloWorld](<https://github.com/atomicgo/pool/blob/main/template.go#L4>)
<a name="Config"></a>
## type [Config](<https://github.com/atomicgo/pool/blob/main/pool.go#L12-L15>)

Config struct defines the configuration parameters for the Pool. \- MaxWorkers: The maximum number of concurrent workers in the pool. \- Timeout: The maximum duration for processing a single task. If a task takes longer, it will be terminated.

```go
func HelloWorld() string
type Config struct {
MaxWorkers int
Timeout time.Duration
}
```

HelloWorld returns \`Hello, World\!\`.
<a name="ErrorHandler"></a>
## type [ErrorHandler](<https://github.com/atomicgo/pool/blob/main/pool.go#L19>)

<details><summary>Example</summary>
<p>
ErrorHandler is a function type for handling errors. It provides a way for users to define custom error handling logic. The function receives an error and a pointer to the pool, allowing users to log errors, modify the pool, or perform other actions.

```go
type ErrorHandler[T any] func(error, *Pool[T])
```

<a name="Pool"></a>
## type [Pool](<https://github.com/atomicgo/pool/blob/main/pool.go#L23-L31>)

Pool struct represents a pool of workers processing tasks of type T. It encapsulates the task handling logic, error handling, and synchronization mechanisms.

```go
package main
type Pool[T any] struct {
// contains filtered or unexported fields
}
```

import (
"atomicgo.dev/template"
"fmt"
)
<a name="New"></a>
### func [New](<https://github.com/atomicgo/pool/blob/main/pool.go#L36>)

func main() {
fmt.Println(template.HelloWorld())
}
```go
func New[T any](config Config) *Pool[T]
```

#### Output
New creates and returns a new pool with the specified configuration. It initializes the internal structures but does not start the worker goroutines. \- config: Configuration settings for the pool, including max workers and task timeout.

<a name="Pool[T].Add"></a>
### func \(\*Pool\[T\]\) [Add](<https://github.com/atomicgo/pool/blob/main/pool.go#L113>)

```go
func (p *Pool[T]) Add(item T)
```
Hello, World!

Add enqueues a task into the pool. If the pool's worker goroutines are running, the task will be picked up for processing. If the pool is not running or has been closed, the behavior of Add is undefined and may result in a deadlock or panic. \- item: The task to be added to the pool for processing.

<a name="Pool[T].Close"></a>
### func \(\*Pool\[T\]\) [Close](<https://github.com/atomicgo/pool/blob/main/pool.go#L119>)

```go
func (p *Pool[T]) Close()
```

</p>
</details>
Close gracefully shuts down the pool. It stops accepting new tasks and waits for all ongoing tasks to complete. This method should be called to ensure a clean shutdown of the pool.

<a name="Pool[T].Kill"></a>
### func \(\*Pool\[T\]\) [Kill](<https://github.com/atomicgo/pool/blob/main/pool.go#L126>)

```go
func (p *Pool[T]) Kill()
```

Kill immediately stops all workers in the pool. It cancels the context, causing all worker goroutines to exit. Any ongoing tasks may be left unfinished. This method is useful for emergency shutdown scenarios.

<a name="Pool[T].SetErrorHandler"></a>
### func \(\*Pool\[T\]\) [SetErrorHandler](<https://github.com/atomicgo/pool/blob/main/pool.go#L57>)

```go
func (p *Pool[T]) SetErrorHandler(handler ErrorHandler[T]) *Pool[T]
```

SetErrorHandler sets a custom error handling function for the pool. It is optional. The error handler allows custom logic to be executed when a task processing results in an error. \- handler: The function to be called when a task encounters an error.

<a name="Pool[T].SetHandler"></a>
### func \(\*Pool\[T\]\) [SetHandler](<https://github.com/atomicgo/pool/blob/main/pool.go#L49>)

```go
func (p *Pool[T]) SetHandler(handler func(context.Context, T) error) *Pool[T]
```

SetHandler sets the task handling function for the pool. It must be called before starting the pool. The handler function takes a context \(for timeout control\) and a task of type T, and returns an error. \- handler: The function that will be called to process each task.

<a name="Pool[T].Start"></a>
### func \(\*Pool\[T\]\) [Start](<https://github.com/atomicgo/pool/blob/main/pool.go#L64>)

```go
func (p *Pool[T]) Start()
```

Start initiates the worker goroutines. It should be called after setting up the task handler and optionally the error handler. This method spins up MaxWorkers number of goroutines, each listening for tasks to process.

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

Expand Down

0 comments on commit 3405ef6

Please sign in to comment.