README
¶
Generic Render Worker Methodology
This package provides a small, explicit API for CPU-heavy UI work that should run off the main thread.
1) Open a fixed worker pool
Use BuildRenderWorkerPool from the app/runtime side with explicit size and queue settings.
2) Register typed handlers in the worker
Use SetRenderWorkerDecodedHandler from the worker side:
- request name
- typed request/response function
DecodedHandlerOptionsguardrails
Guardrails:
ShouldRecoverPanicisolates crashes from user code.GetRequestTimeoutbounds long-running user logic.
3) Keep custom experiments isolated
Put local or product-specific handlers in one function (for example setBackgroundWorkerCustomHandlers) so experimentation does not leak into core worker wiring.
4) Dispatch from the app by request name
The app uses interop.RequestWorkerDecoded against either one worker or WorkerPool.
Start with one request shape, then add request names as new tasks are introduced.
5) Multi-worker lane optimization primitives
This package includes reusable lane-dispatch optimizations ported from Example 201:
BuildRenderWorkerAdaptiveChunkBoundsfor weighted contiguous chunk partitioningBuildRenderWorkerChunkPlansfor concrete chunk plans with estimated work weightsBuildRenderWorkerLanePlansfor weighted greedy worker-lane balancingRequestRenderWorkerChunkBatchesfor one-request-per-lane batched fanout with chunk-index aggregationBuildRenderWorkerChunkLocalIndexesfor dirty-index localization inside one chunk payloadRenderWorkerGenerationTrackerfor request-generation stale-drop guards
6) Fail soft
If pooled worker requests fail, prefer a documented fallback path (for example sync render on main thread) so the UI remains usable.
Documentation
¶
Index ¶
- func BuildRenderWorkerAdaptiveChunkBounds(parseWeights []int, parseChunkCount int) [][2]int
- func BuildRenderWorkerChunkLocalIndexes(parseGlobalIndexes []int, parseStart int, parseEnd int) []int
- func BuildRenderWorkerPool(parseCtx context.Context, parseOptions PoolOptions) (interop.WorkerPool, error)
- func RequestRenderWorkerChunkBatches[BatchReq any, BatchRes any, ChunkRes any](parseOptions BatchDispatchOptions[BatchReq, BatchRes, ChunkRes]) ([]ChunkRes, error)
- func SetRenderWorkerDecodedHandler[Req any, Res any](parseDispatcher *RenderWorkerDispatcher, parseRequestName string, ...) error
- type BatchDispatchOptions
- type DecodedHandlerOptions
- type Handler
- type PoolOptions
- type RenderWorkerChunkPlan
- type RenderWorkerDispatcher
- type RenderWorkerGenerationTracker
- type RenderWorkerLanePlan
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildRenderWorkerAdaptiveChunkBounds ¶
BuildRenderWorkerAdaptiveChunkBounds partitions index ranges into contiguous chunks with roughly balanced weight.
func BuildRenderWorkerChunkLocalIndexes ¶
func BuildRenderWorkerChunkLocalIndexes(parseGlobalIndexes []int, parseStart int, parseEnd int) []int
BuildRenderWorkerChunkLocalIndexes filters global dirty indexes into one chunk-local [start, end) index set.
func BuildRenderWorkerPool ¶
func BuildRenderWorkerPool(parseCtx context.Context, parseOptions PoolOptions) (interop.WorkerPool, error)
BuildRenderWorkerPool opens one fixed-size pool of Go WASM workers for generic render tasks.
func RequestRenderWorkerChunkBatches ¶
func RequestRenderWorkerChunkBatches[BatchReq any, BatchRes any, ChunkRes any](parseOptions BatchDispatchOptions[BatchReq, BatchRes, ChunkRes]) ([]ChunkRes, error)
RequestRenderWorkerChunkBatches fans out one lane-batched request plan and aggregates chunk results into stable chunk-index order.
func SetRenderWorkerDecodedHandler ¶
func SetRenderWorkerDecodedHandler[Req any, Res any](parseDispatcher *RenderWorkerDispatcher, parseRequestName string, parseHandle func(context.Context, Req) (Res, error), parseOptions DecodedHandlerOptions) error
SetRenderWorkerDecodedHandler builds and registers one typed decoded request handler on the dispatcher.
Types ¶
type BatchDispatchOptions ¶
type BatchDispatchOptions[BatchReq any, BatchRes any, ChunkRes any] struct { GetCtx context.Context GetRequestName string GetExpectedGeneration uint64 GetRequesters []interop.WorkerRequester GetLanePlans []RenderWorkerLanePlan GetChunkCount int BuildBatchRequest func(RenderWorkerLanePlan) BatchReq GetBatchChunks func(BatchRes) []ChunkRes GetChunkIndex func(ChunkRes) int GetBatchGeneration func(BatchRes) uint64 GetChunkGeneration func(ChunkRes) uint64 IsBatchStale func(BatchRes) bool IsChunkStale func(ChunkRes) bool HandlePartialChunkResults func([]ChunkRes) }
BatchDispatchOptions configures one lane-batched multi-worker request pass that aggregates chunk results by index.
type DecodedHandlerOptions ¶
DecodedHandlerOptions configures safety guards for typed decoded worker handlers.
type Handler ¶
type Handler func(interop.WorkerScope, interop.WorkerMessage)
Handler handles one worker request routed through RenderWorkerDispatcher.
func BuildRenderWorkerDecodedHandler ¶
func BuildRenderWorkerDecodedHandler[Req any, Res any](parseRequestName string, parseHandle func(context.Context, Req) (Res, error)) Handler
BuildRenderWorkerDecodedHandler builds one typed request handler that decodes payloads and posts typed results.
func BuildRenderWorkerDecodedHandlerWithOptions ¶
func BuildRenderWorkerDecodedHandlerWithOptions[Req any, Res any](parseRequestName string, parseHandle func(context.Context, Req) (Res, error), parseOptions DecodedHandlerOptions) Handler
BuildRenderWorkerDecodedHandlerWithOptions builds one typed request handler with configurable guard rails for user-defined code.
type PoolOptions ¶
type PoolOptions struct {
GetSize int
GetQueueLimit int
GetRuntimeURL string
GetWASMURL string
GetNamePrefix string
IsReady bool
GetReadyTimeout time.Duration
}
PoolOptions configures one generic Go WASM render worker pool.
type RenderWorkerChunkPlan ¶
RenderWorkerChunkPlan stores one contiguous chunk and its estimated work weight.
func BuildRenderWorkerChunkPlans ¶
func BuildRenderWorkerChunkPlans(parseChunkBounds [][2]int, parseWeights []int) []RenderWorkerChunkPlan
BuildRenderWorkerChunkPlans materializes weighted chunk plans from contiguous chunk bounds.
type RenderWorkerDispatcher ¶
type RenderWorkerDispatcher struct {
// contains filtered or unexported fields
}
RenderWorkerDispatcher routes worker request messages to extensible named handlers.
func BuildRenderWorkerDispatcher ¶
func BuildRenderWorkerDispatcher(parseDefaultRequestName string) *RenderWorkerDispatcher
BuildRenderWorkerDispatcher builds one request dispatcher with an optional default request name.
func (*RenderWorkerDispatcher) HandleRenderWorkerMessage ¶
func (parseDispatcher *RenderWorkerDispatcher) HandleRenderWorkerMessage(parseScope interop.WorkerScope, parseMessage interop.WorkerMessage)
HandleRenderWorkerMessage dispatches one worker message to the configured request handler.
func (*RenderWorkerDispatcher) SetRenderWorkerHandler ¶
func (parseDispatcher *RenderWorkerDispatcher) SetRenderWorkerHandler(parseRequestName string, parseHandler Handler) error
SetRenderWorkerHandler stores one named worker request handler for later dispatch.
type RenderWorkerGenerationTracker ¶
type RenderWorkerGenerationTracker struct {
// contains filtered or unexported fields
}
RenderWorkerGenerationTracker tracks latest request generations for stale-drop checks.
func BuildRenderWorkerGenerationTracker ¶
func BuildRenderWorkerGenerationTracker() *RenderWorkerGenerationTracker
BuildRenderWorkerGenerationTracker builds one empty request-generation tracker.
func (*RenderWorkerGenerationTracker) GetRenderWorkerLatestGeneration ¶
func (parseTracker *RenderWorkerGenerationTracker) GetRenderWorkerLatestGeneration(parseRequestName string) uint64
GetRenderWorkerLatestGeneration returns the latest tracked generation for one request name.
func (*RenderWorkerGenerationTracker) ShouldRenderWorkerDropStaleRequest ¶
func (parseTracker *RenderWorkerGenerationTracker) ShouldRenderWorkerDropStaleRequest(parseRequestName string, parseGeneration uint64) bool
ShouldRenderWorkerDropStaleRequest reports whether one generation is stale for the named request and updates tracker state.
type RenderWorkerLanePlan ¶
type RenderWorkerLanePlan struct {
GetWorkerIndex int
GetTotalWeight int
GetChunkPlans []RenderWorkerChunkPlan
}
RenderWorkerLanePlan stores one worker-lane assignment and its total estimated work weight.
func BuildRenderWorkerLanePlans ¶
func BuildRenderWorkerLanePlans(parseWorkerCount int, parseChunkPlans []RenderWorkerChunkPlan) []RenderWorkerLanePlan
BuildRenderWorkerLanePlans assigns chunk plans to worker lanes using weighted greedy balancing.
Source Files