locate

README

locate

Purpose

locate orchestrates font resolution across one or more providers.

It exposes async resolution primitives and a context-aware variant for cancellation/deadline control.

API

• type FontLocator
• type FontLocatorWithContext
• type FontPromise
• type FontRegistry
• type ResolverPipeline
• ResolveFontLoc(desc, resolvers...) FontPromise
• ResolveFontLocWithContext(ctx, desc, resolvers...) FontPromise
• NewResolverPipeline(reg, resolvers...) ResolverPipeline
• (ResolverPipeline).Resolve(ctx, desc) FontPromise

Resolution flow:

1. Try registry cache.
2. Try resolvers in order.
3. Cache successful result.
4. Return fallback font with error when unresolved.

ResolveFontLoc* uses the global registry. Use ResolverPipeline when clients need their own registry instance.

Example Applications

1. Resolve through a resolver chain

promise := locate.ResolveFontLoc(desc, systemResolver, googleResolver, fallbackResolver)
sf, err := promise.Font()

For clients who need their own registry instance, create a custom pipeline:

registry := fontregistry.New() // implements locate.FontRegistry
pipeline := locate.NewResolverPipeline(registry,
	systemResolver,
	googleResolver,
	fallbackResolver)
sf, err := pipeline.Resolve(context.Background(), desc).Font()

2. Context-aware waiting

ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()

promise := locate.ResolveFontLocWithContext(ctx, desc, ctxResolver)
sf, err := promise.FontWithContext(ctx)

3. Custom registry pipeline

reg := newClientRegistry() // implements locate.FontRegistry
pipeline := locate.NewResolverPipeline(reg, ctxResolver)
sf, err := pipeline.Resolve(context.Background(), desc).Font()

Documentation

Overview

Package locate defines resolver function types and async font resolution helpers.

Index

• type FontLocator
• type FontLocatorWithContext
• type FontPromise
  • func ResolveFontLoc(desc fontfind.Descriptor, resolvers ...FontLocator) FontPromise
  • func ResolveFontLocWithContext(ctx context.Context, desc fontfind.Descriptor, ...) FontPromise
• type FontRegistry
• type ResolverPipeline
  • func NewResolverPipeline(reg FontRegistry, resolvers ...FontLocatorWithContext) ResolverPipeline
  • func (pipeline ResolverPipeline) Resolve(ctx context.Context, desc fontfind.Descriptor) FontPromise

Types

type FontLocator

type FontLocator func(fontfind.Descriptor) (fontfind.ScalableFont, error)

FontLocator resolves a scalable font for a descriptor.

type FontLocatorWithContext

type FontLocatorWithContext func(context.Context, fontfind.Descriptor) (fontfind.ScalableFont, error)

FontLocatorWithContext is a context-aware variant of FontLocator. Implementations should respect cancellation/deadlines of ctx if possible.

type FontPromise

type FontPromise interface {
	Font() (fontfind.ScalableFont, error)
	FontWithContext(ctx context.Context) (fontfind.ScalableFont, error)
}

FontPromise runs font searching asynchronously in the background. Font blocks until completion, and FontWithContext allows waiting with caller-controlled cancellation and deadlines.

func ResolveFontLoc

func ResolveFontLoc(desc fontfind.Descriptor, resolvers ...FontLocator) FontPromise

ResolveFontLoc resolves a scalable font using the given resolver chain.

It first checks the global font registry cache. On a cache miss, resolvers are tried in the given order until one succeeds. A successful resolution is stored in the registry cache. If all resolvers fail, it returns the registry fallback font together with a not-found error.

The search runs asynchronously and returns a FontPromise.

func ResolveFontLocWithContext

func ResolveFontLocWithContext(ctx context.Context, desc fontfind.Descriptor, resolvers ...FontLocatorWithContext) FontPromise

ResolveFontLocWithContext is the context-aware variant of ResolveFontLoc. The search goroutine and resolver calls receive ctx.

type FontRegistry

type FontRegistry interface {
	GetFont(string) (fontfind.ScalableFont, error)
	StoreFont(string, fontfind.ScalableFont)
	FallbackFont() (fontfind.ScalableFont, error)
}

FontRegistry is the cache contract required by ResolverPipeline.

type ResolverPipeline

type ResolverPipeline struct {
	// contains filtered or unexported fields
}

ResolverPipeline orchestrates resolver execution with a configurable registry.

func NewResolverPipeline

func NewResolverPipeline(reg FontRegistry, resolvers ...FontLocatorWithContext) ResolverPipeline

NewResolverPipeline constructs a resolver driver with an optional custom registry. If reg is nil, the global registry singleton is used.

func (ResolverPipeline) Resolve

func (pipeline ResolverPipeline) Resolve(ctx context.Context, desc fontfind.Descriptor) FontPromise

Resolve resolves a font request asynchronously using this pipeline's registry and resolvers.