Documentation
¶
Overview ¶
Package parka provides managed concurrency for tasks identified by keys.
For simple use cases, top-level functions like Collect concurrently map over sets of keys with duplicate suppression and optional bounded concurrency. For advanced use cases, the underlying Map type additionally exposes persistent caching of previous results, dynamically adjustable concurrency limits, and more flexible task prioritization.
This version of Parka is suited for work that doesn't require cache eviction, like a main package running a single batch-type workflow or short-lived maps that are disposed of after a single use.
Index ¶
- Variables
- func Collect[K comparable, V any](ctx context.Context, keys []K, handle func(context.Context, K) (V, error)) ([]V, error)
- func CollectLimited[K comparable, V any](ctx context.Context, limit int, keys []K, ...) (values []V, err error)
- type Handle
- type KeyMutex
- type Map
- func (m *Map[K, V]) Collect(keys ...K) ([]V, error)
- func (m *Map[K, V]) DequeueAll() []K
- func (m *Map[K, V]) Get(key K) (V, error)
- func (m *Map[K, V]) Inform(keys ...K)
- func (m *Map[K, V]) InformFront(keys ...K)
- func (m *Map[K, V]) Limit(limit int)
- func (m *Map[K, V]) Stats() Stats
- func (m *Map[K, V]) WaitAttached()
- type Set
- type Stats
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrHandlerGoexit = errors.New("parka: handler executed runtime.Goexit")
ErrHandlerGoexit is panicked when retrieving a Map result for which the corresponding handler called runtime.Goexit.
var ErrTaskEjected = errors.New("task ejected from queue")
ErrTaskEjected is the error returned when retrieving a Map result for which the corresponding handler run was canceled.
Functions ¶
func Collect ¶
func Collect[K comparable, V any]( ctx context.Context, keys []K, handle func(context.Context, K) (V, error), ) ([]V, error)
Collect runs a handler function once per unique key in a distinct goroutine, and coalesces the results.
If any handler returns an error, Collect cancels the remaining handlers' contexts, waits for all handlers to finish, and returns that error. Otherwise, it returns a slice of values corresponding to the provided keys.
Collect doesn't recover panics; they crash the program if not recovered within the handler. If the handler calls runtime.Goexit, Collect cancels remaining work as described above, then panics with ErrHandlerGoexit.
Example ¶
package main
import (
"context"
"crypto/sha256"
"encoding/hex"
"fmt"
"sync/atomic"
"github.com/featherbread/parka"
)
func main() {
var calls atomic.Uint64
inputs := []string{"hello", "world", "hello", "there"}
hashes, _ := parka.Collect(context.Background(), inputs,
func(_ context.Context, input string) (string, error) {
calls.Add(1)
hash := sha256.Sum256([]byte(input))
return hex.EncodeToString(hash[:]), nil
})
fmt.Println(
calls.Load(),
len(hashes),
hashes[0] == hashes[2],
hashes[0],
)
}
Output: 3 4 true 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
func CollectLimited ¶
func CollectLimited[K comparable, V any]( ctx context.Context, limit int, keys []K, handle func(context.Context, K) (V, error), ) (values []V, err error)
CollectLimited behaves like Collect, but limits the number of goroutines that may concurrently handle keys. It panics if the provided limit is less than 1.
If any handler returns an error or Goexits, CollectLimited cancels in-flight handlers as described in Collect, and leaves queued keys unhandled.
Example ¶
package main
import (
"context"
"fmt"
"log"
"net/http"
"net/http/httptest"
"github.com/featherbread/parka"
)
func main() {
srv := httptest.NewServer(
http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
}))
defer srv.Close()
var (
ctx = context.Background()
urls = []string{
"https://www.example.com/",
"https://www.example.net/",
// ...
}
// Note that even with concurrency > len(urls), Parka never spawns more
// goroutines than necessary to complete a task.
concurrency = 5
)
codes, err := parka.CollectLimited(ctx, concurrency, urls,
func(ctx context.Context, url string) (int, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodHead, url, nil)
if err != nil {
return 0, err
}
resp, err := srv.Client().Do(req)
if err != nil {
return 0, err
}
resp.Body.Close()
return resp.StatusCode, nil
})
if err != nil {
log.Printf("Failed to HEAD all URLs: %v", err)
}
fmt.Println(codes)
}
Output: [200 200]
Types ¶
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle allows a handler to interact with its parent Map.
Handle methods may be called in goroutines separate from the handler's own. In the terminology of the Go memory model, the return of every Handle call must be synchronized before the handler's termination.
type KeyMutex ¶
type KeyMutex[K comparable] struct { // contains filtered or unexported fields }
KeyMutex provides mutual exclusion among operations targeting specific comparable keys. The zero value is a valid KeyMutex with no locked keys.
A KeyMutex must not be copied after first use.
Example ¶
package main
import (
"bytes"
"io"
"net/http"
"net/url"
"github.com/featherbread/parka"
)
func main() {
var hostsMu parka.KeyMutex[string]
pages := parka.NewMap(func(ph *parka.Handle, pageURL string) ([]byte, error) {
parsedURL, err := url.Parse(pageURL)
if err != nil {
return nil, err
}
// Limit concurrent requests to any single host while allowing concurrency
// across distinct hosts.
hostsMu.LockDetached(ph, parsedURL.Hostname())
defer hostsMu.Unlock(parsedURL.Hostname())
var body bytes.Buffer
resp, err := http.Get(pageURL)
if err == nil {
_, err = io.Copy(&body, resp.Body)
resp.Body.Close()
}
return body.Bytes(), err
})
// Even though we queue requests for the same hostname together, the KeyMutex
// ensures our two concurrent requests always hit different hosts.
pages.Limit(2)
pages.Collect(
// example.com
"https://www.example.com/index.html",
"https://www.example.com/faq.html",
"https://www.example.com/contact.html",
// example.net
"https://www.example.net/index.html",
"https://www.example.net/faq.html",
"https://www.example.net/contact.html",
// ...
)
}
Output:
func (*KeyMutex[K]) Lock ¶
func (km *KeyMutex[K]) Lock(key K)
Lock blocks the calling goroutine until any other lock on the provided key is released.
func (*KeyMutex[K]) LockDetached ¶
LockDetached blocks the calling Map handler until any other lock on the provided key is released. If the lock isn't immediately available, it detaches the handler from the map's concurrency limit while it waits for the lock, and reattaches before returning.
type Map ¶
type Map[K comparable, V any] struct { // contains filtered or unexported fields }
Map runs a handler function once per key in a distinct goroutine and caches its result.
Each result includes a value and error. Errors receive no special treatment; they're cached as part of the key's result, and the corresponding handler is never retried.
Map doesn't recover panics; they crash the program if not recovered within the handler. If the handler calls runtime.Goexit, retrieving the key's result panics with ErrHandlerGoexit.
Concurrency ¶
New maps permit an effectively unlimited number of goroutines (math.MaxInt) to concurrently handle new keys. Map.Limit can change this at any time. Note that maps do not spawn more goroutines than are required to handle known keys, regardless of the concurrency limit.
Queueing ¶
When concurrency is limited, the map queues new keys for later handling in the background. Keys are handled in FIFO order unless they're first introduced by Map.InformFront rather than an explicit or implicit Map.Inform, providing minimal prioritization support for urgent tasks.
Inform and InformFront enqueue any new keys introduced within a single call as a single batch. When the new keys are logically associated with a single larger operation, this batching is intended to increase the number of larger operations that can finish completely before an unexpected termination. When retrieving results with repeated Map.Get calls rather than Map.Collect, it's recommended to pre-queue the keys as shown in the Inform example.
Detaching ¶
Any handler may call Handle.Detach to exclude itself from the map's concurrency limit for the remainder of its lifetime, or until it calls Handle.Reattach.
Detaching is intended for use by handlers that share concurrency-limited resources with some (but not all) of their sibling handlers. If a handler finds that a resource is in use, detaching can allow the map's limited concurrency to be used for an unrelated handler rather than spent waiting. KeyMutex facilitates this pattern for resources that can be identified by a key; its example shows a KeyMutex over hostnames limiting concurrent fetches of arbitrary URLs from any one host.
Example ¶
package main
import (
"fmt"
"github.com/featherbread/parka"
)
func main() {
m := parka.NewMap(func(_ *parka.Handle, x int) (int, error) {
return x % 3, nil
})
mods, _ := m.Collect(0, 1, 2, 3, 4, 5)
fmt.Println(mods)
}
Output: [0 1 2 0 1 2]
Example (Inform) ¶
package main
import (
"errors"
"fmt"
"github.com/featherbread/parka"
)
func main() {
m := parka.NewMap(func(_ *parka.Handle, x int) (int, error) {
if x >= 3 {
return 0, errors.New("out of range")
}
return x * x, nil
})
// Use Inform to pre-submit keys for handling.
m.Inform(0, 1, 2, 3, 4, 5)
// Even though we use Get to obtain each key's error
// (rather than coalesce to a single error with Collect),
// all handlers are able to run concurrently.
var errs []error
for x := range 6 {
if _, err := m.Get(x); err != nil {
errs = append(errs, err)
}
}
fmt.Println(len(errs))
}
Output: 3
func NewMap ¶
func NewMap[K comparable, V any](handle func(*Handle, K) (V, error)) *Map[K, V]
NewMap creates a Map with the provided handler.
func (*Map[K, V]) Collect ¶
Collect informs the map of the keys as if by Map.Inform, then returns a slice of values corresponding to the keys, or returns the first error with respect to the order of the keys without waiting for the map to handle any subsequent keys.
A consequence of this definition is that Collect can't return any key's error until all of its preceding keys have been handled, which creates subtle pitfalls around behaviors like task cancellation. The family of top-level Collect functions demonstrates a robust strategy for context.Context handling with a single-use Map.
func (*Map[K, V]) DequeueAll ¶
func (m *Map[K, V]) DequeueAll() []K
DequeueAll removes and returns any queued keys that haven't been picked up for handling.
DequeueAll unblocks goroutines awaiting the results of the dequeued keys by yielding the zero value of V and ErrTaskEjected. Any retrieval of a dequeued key started after DequeueAll returns will re-inform the map of the key. DequeueAll has no effect on cached results or handlers in flight.
func (*Map[K, V]) Get ¶
Get informs the map of the key as if by Map.Inform, blocks until it has handled the key, then returns the key's result.
func (*Map[K, V]) Inform ¶
func (m *Map[K, V]) Inform(keys ...K)
Inform advises the map of keys that it should ensure are handled and cached as soon as possible.
Inform has no effect on keys already handled or pending. When concurrency limits prohibit immediate handling of all keys, the new keys among those provided are enqueued at the back of a work queue, in the order given, without interleaving the keys of any other enqueue operation. A future Map.InformFront call may interpose new keys between those enqueued in a single Inform call.
func (*Map[K, V]) InformFront ¶
func (m *Map[K, V]) InformFront(keys ...K)
InformFront behaves like Map.Inform, but enqueues new keys at the front of the map's work queue rather than the back. Like Inform, it doesn't affect the order of keys already pending.
func (*Map[K, V]) Limit ¶
Limit updates the map's concurrency limit for handling pending keys. It panics if the provided limit is less than 1.
Limit may be called at any time, even while handlers are running. The map immediately spawns handlers for as many pending keys as an increased limit allows, or permits in-flight handlers in violation of a decreased limit to finish in the background.
func (*Map[K, V]) WaitAttached ¶
func (m *Map[K, V]) WaitAttached()
WaitAttached blocks until the map has no handlers running within its concurrency limit. Handlers that detach from the map and don't reattach before the completion of all attached handlers may still be running after WaitAttached returns.
type Set ¶
type Set[K comparable] struct { *Map[K, struct{}] }
Set wraps a Map whose handlers return no meaningful value with simplified error-only result APIs.
The use of the term "set" could be considered objectionable when each key still maps to a meaningful error value. It may help to think of the handler as determining whether each key belongs to the set, and returning a non-nil error to explain why a given key isn't a member of the set.
func NewSet ¶
func NewSet[K comparable](handle func(*Handle, K) error) Set[K]
NewSet is analogous to NewMap, but accepts a simplified handler returning only an error.
func (Set[K]) Collect ¶
Collect is analogous to Map.Collect.