Documentation
¶
Overview ¶
Package types defines the fundamental data structures, interfaces, and errors that form the vocabulary of the Flow Control system. It establishes the core data contracts for the request lifecycle, from initial submission to final, reportable outcome.
The Request Lifecycle ¶
The primary entry point to the `controller.FlowController` is the synchronous `EnqueueAndWait` method. The types in this package are designed to model a request's journey through this blocking call.
A client first constructs an object that implements the `FlowControlRequest` interface. This is the "raw" input, containing the essential data for the request, such as its `FlowID` and `ByteSize`. This object is passed to `EnqueueAndWait`.
Internally, the `controller.FlowController` wraps the `FlowControlRequest` in an object that implements the `QueueItemAccessor` interface. This is an enriched, read-only view used by policies and queues. It adds internal metadata like `EnqueueTime` and `EffectiveTTL`.
If the request is accepted and added to a SafeQueue, the queue creates a `QueueItemHandle`. This is an opaque, queue-specific handle that the controller uses to perform targeted operations (like removal) without needing to know the queue's internal implementation details.
The `EnqueueAndWait` method blocks until the request reaches a terminal state. This final state is reported using a `QueueOutcome` enum and a corresponding `error`.
Final State Reporting: Outcomes and Errors ¶
This combination of a concise enum and a detailed error provides a clear, machine-inspectable result.
`QueueOutcome`: A low-cardinality enum summarizing the final result (e.g., `QueueOutcomeDispatched`, `QueueOutcomeRejectedCapacity`). This is ideal for metrics.
`error`: For any non-dispatch outcome, a specific sentinel error is returned. These are nested to provide rich context. Callers can use `errors.Is()` to check for the general class of failure (`ErrRejected` or `ErrEvicted`), and then unwrap the error to find the specific cause (e.g., `ErrQueueAtCapacity` or `ErrTTLExpired`).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrRejected is a sentinel error indicating a request was rejected by the `controller.FlowController` *before* being // formally enqueued. Errors returned by `FlowController.EnqueueAndWait()` that signify pre-queue rejection will wrap // this error. // // Callers should use `errors.Is(err, ErrRejected)` to check for this general class of failure. ErrRejected = errors.New("request rejected pre-queue") // ErrEvicted is a sentinel error indicating a request was removed from a queue *after* being successfully enqueued, // but for reasons other than successful dispatch (e.g., TTL expiry, displacement). Errors returned by // `FlowController.EnqueueAndWait()` that signify post-queue eviction will wrap this error. // // Callers should use `errors.Is(err, ErrEvicted)` to check for this general class of failure. ErrEvicted = errors.New("request evicted from queue") )
var ( // ErrTTLExpired indicates a request was evicted from a queue because its effective Time-To-Live expired. ErrTTLExpired = errors.New("request TTL expired") // ErrContextCancelled indicates a request was evicted because its associated context (from // `FlowControlRequest.Context()`) was cancelled. This error typically wraps the underlying `context.Canceled` or // `context.DeadlineExceeded` error. ErrContextCancelled = errors.New("request context cancelled") )
The following errors occur when a request, already in a SafeQueue, is removed for reasons other than dispatch. When returned by `FlowController.EnqueueAndWait()`, these specific errors will typically be wrapped by `ErrEvicted`.
var ( // ErrFlowControllerNotRunning indicates that an operation could not complete or an item was evicted because the // `controller.FlowController` is not running or is in the process of shutting down. // // When returned by `FlowController.EnqueueAndWait()`, this will be wrapped by `ErrRejected` (if rejection happens // before internal queuing) or `ErrEvicted` (if eviction happens after internal queuing). ErrFlowControllerNotRunning = errors.New("flow controller is not running") )
var ( // ErrQueueAtCapacity indicates that a request could not be enqueued because queue capacity limits were met. ErrQueueAtCapacity = errors.New("queue at capacity") )
The following errors can occur before a request is formally added to a SafeQueue. When returned by `FlowController.EnqueueAndWait()`, these specific errors will typically be wrapped by `ErrRejected`.
Functions ¶
This section is empty.
Types ¶
type QueueOutcome ¶
type QueueOutcome int
QueueOutcome represents the high-level final state of a request's lifecycle within the `controller.FlowController`.
It is returned by `FlowController.EnqueueAndWait()` along with a corresponding error. This enum is designed to be a low-cardinality label ideal for metrics, while the error provides fine-grained details for non-dispatched outcomes.
const ( // QueueOutcomeNotYetFinalized indicates the request has not yet been finalized by the `controller.FlowController`. // This is an internal default value and should never be returned by `FlowController.EnqueueAndWait()`. QueueOutcomeNotYetFinalized QueueOutcome = iota // QueueOutcomeDispatched indicates the request was successfully processed by the `controller.FlowController` and // unblocked for the caller to proceed. // The associated error from `FlowController.EnqueueAndWait()` will be nil. QueueOutcomeDispatched // QueueOutcomeRejectedCapacity indicates rejection because queue capacity limits were met. // The associated error will wrap `ErrQueueAtCapacity` (and `ErrRejected`). QueueOutcomeRejectedCapacity // QueueOutcomeRejectedOther indicates rejection for reasons other than capacity before the request was formally // enqueued. // The specific underlying cause can be determined from the associated error (e.g., a nil request, an unregistered // flow ID, or controller shutdown), which will be wrapped by `ErrRejected`. QueueOutcomeRejectedOther // QueueOutcomeEvictedTTL indicates eviction from a queue because the request's effective Time-To-Live expired. // The associated error will wrap `ErrTTLExpired` (and `ErrEvicted`). QueueOutcomeEvictedTTL // QueueOutcomeEvictedContextCancelled indicates eviction from a queue because the request's own context (from // `FlowControlRequest.Context()`) was cancelled. // The associated error will wrap `ErrContextCancelled` (which may further wrap the underlying `context.Canceled` or // `context.DeadlineExceeded` error) (and `ErrEvicted`). QueueOutcomeEvictedContextCancelled // QueueOutcomeEvictedOther indicates eviction from a queue for reasons not covered by more specific eviction // outcomes. // The specific underlying cause can be determined from the associated error (e.g., controller shutdown while the item // was queued), which will be wrapped by `ErrEvicted`. QueueOutcomeEvictedOther )
func (QueueOutcome) String ¶
func (o QueueOutcome) String() string
String returns a human-readable string representation of the QueueOutcome.
Source Files