Documentation
¶
Overview ¶
Package handler contains the basic Handler units used to compose reconciliation loops for a controller.
You write functions or types that implement the ContextHandler interface, and then compose them via Handlers and Builders.
Builders are used for chaining Handler construction together, and Handlers are the things that actually process requests. It can be useful to go back and forth between Builders and Handlers (to wrap startup behavior or runtime behavior respectively), so each type has methods to convert between them.
See other files for helpers to compose or wrap handlers and builders.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var NoopHandler = NewHandler(ContextHandlerFunc(func(_ context.Context) {}), NextKey)
NoopHandler is a handler that does nothing
Functions ¶
This section is empty.
Types ¶
type Builder ¶
Builder is a function that takes a list of "next" Handlers and returns a single Handler.
Example ¶
ctx, cancel := context.WithCancel(context.Background()) defer cancel() // Builders allow for relatively painless restructuring of the handler // state machine: firstStageBuilder(secondStageBuilder(NoopHandler)).Handle(ctx) // reverse the order: secondStageBuilder(firstStageBuilder(NoopHandler)).Handle(ctx) // Builders are a lower-level building block // See Chain and Parallel for helpers that make building larger state // machines more ergonomic.
Output: the first step the second step the second step the first step
func Chain ¶
Chain chains a set of handler.Builder together
Example ¶
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
Chain(
firstStageBuilder,
secondStageBuilder,
).Handler("firstThenSecond").Handle(ctx)
Output: the first step the second step
func Parallel ¶
Parallel creates a new handler.Builder that runs a set of handler.Builder in parallel
Example ¶
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// slow down the first stage to get a deterministic output
slowFirstStage := func(next ...Handler) Handler {
time.Sleep(5 * time.Millisecond)
return firstStageBuilder(next...)
}
// These handlers run in parallel, so their contexts are independent
// i.e. FirstStage.next and SecondStage.next are both NoopHandlers
// Any work that is done that needs to be used later on should use
// typedctx.Boxed contexts so that the parallel steps can "fill in"
// a predefined space.
Parallel(
slowFirstStage,
secondStageBuilder,
).Handler("firstAndSecond").Handle(ctx)
Output: the second step the first step
type BuilderComposer ¶
BuilderComposer is a function that composes sets of handler.Builder into one handler.Builder, see `Chain` and `Parallel`.
type ContextHandler ¶
ContextHandler is the interface for a "chunk" of reconciliation. It either returns, often by adjusting the current key's place in the queue (i.e. via requeue or done) or calls another handler in the chain.
type ContextHandlerFunc ¶
ContextHandlerFunc is a function type that implements ContextHandler
func (ContextHandlerFunc) Handle ¶
func (f ContextHandlerFunc) Handle(ctx context.Context)
type Handler ¶
type Handler struct {
ContextHandler
// contains filtered or unexported fields
}
Handler wraps a ContextHandler and adds a method to create a corresponding Builder. Handler has a Key id so that t can be dereferenced by handlers that branch into multiple options and need to choose a specific one.
func NewHandler ¶
func NewHandler(h ContextHandler, id Key) Handler
NewHandler assigns an id to a ContextHandler implementation and returns a Handler.
Example ¶
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// NewHandler assigns an id to a ContextHandler
// IDs are most helpful for complex / branching state machines - a simple
// chain of handlers may not need them. `NewTypeHandler` will assign a
// default ID based on the type.
handler := NewHandler(&FirstStage{config: "example", next: NoopHandler}, "theFirstStage")
handler.Handle(ctx)
Output: the first step
func NewHandlerFromFunc ¶
func NewHandlerFromFunc(h ContextHandlerFunc, id Key) Handler
NewHandlerFromFunc creates a new Handler from a ContextHandlerFunc.
func NewTypeHandler ¶
func NewTypeHandler(h ContextHandler) Handler
NewTypeHandler assigns an id based on the underlying type to a ContextHandler implementation and returns a Handler.
Example ¶
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// NewTypeHandler will assign a default ID based on the type.
handler := NewTypeHandler(&FirstStage{config: "example", next: NoopHandler})
handler.Handle(ctx)
Output: the first step
type Handlers ¶
type Handlers []Handler
Handlers adds methods to a list of Handler objects and makes it easy to pick a Handler with a specific ID out of the list.
func (Handlers) Find ¶
Find returns the Handler for the given Key and a boolean that returns true if it was found or false otherwise.
func (Handlers) MustFind ¶
MustFind returns the Handler for the given Key and panics if none is found.
Example ¶
ctx, cancel := context.WithCancel(context.Background()) defer cancel() // Handler IDs allow a Builder to pick out a specific handler from a set // This allows building complex or branching state machines secondStage := secondStageBuilder(NoopHandler).WithID(secondKey) firstStage := firstStageBuilder(secondStage).WithID(firstKey) decisionHandlerBuilder(firstStage, secondStage).Handle(ctx)
Output: the second step
Source Files