Documentation
¶
Overview ¶
Package image provides network image loading with in-memory and disk caching.
The primary entry point is Loader, which fetches images over HTTP, decodes them into standard image.Image values, and caches the results in a two-tier cache (in-memory LRU via Cache, optional filesystem via DiskCache). Concurrent requests for the same URL are deduplicated into a single HTTP request, and callers can cancel individual listeners without affecting others.
Default Loader ¶
DefaultLoader returns a shared process-wide Loader with sensible defaults (100-entry / 100 MB memory cache, 500 MB disk cache under the platform cache directory). The [widgets.NetworkImage] widget uses DefaultLoader automatically.
Supported Formats ¶
This package registers decoders for PNG, JPEG, GIF, and WebP on import. Additional formats can be registered via the standard image.RegisterFormat mechanism.
Custom Loader ¶
Applications that need custom cache sizes, HTTP clients, or headers can construct their own Loader:
loader := image.NewLoader(image.LoaderOptions{
MemoryCache: image.NewCache(image.CacheOptions{MaxEntries: 50}),
Client: myAuthClient,
})
cancel := loader.Load(url, image.LoadOptions{
Headers: map[string]string{"Authorization": "Bearer tok"},
}, func(result image.LoadResult) {
// handle result.Image or result.Err
})
defer cancel()
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is a thread-safe in-memory LRU cache for decoded images.
func NewCache ¶
func NewCache(opts CacheOptions) *Cache
NewCache creates an in-memory LRU cache with the given options.
func (*Cache) Get ¶
Get retrieves an image from the cache. Returns the image and true on hit, or nil and false on miss. A hit promotes the entry to most-recently-used.
type CacheOptions ¶
type CacheOptions struct {
// MaxEntries is the maximum number of images to cache. Default: 100.
MaxEntries int
// MaxBytes is the maximum total decoded size in bytes. Default: 100 MB.
MaxBytes int64
}
CacheOptions configures an in-memory image cache.
type DiskCache ¶
type DiskCache struct {
// contains filtered or unexported fields
}
DiskCache persists raw image bytes to the filesystem. It stores undecoded response bodies so that format detection (image.Decode) works on read.
Keys are hashed with SHA-256 to produce safe filenames. When the cache exceeds MaxBytes, the oldest files by modification time are evicted.
func NewDiskCache ¶
NewDiskCache creates a disk cache rooted at dir. The directory is created if it does not exist. maxBytes controls the total size limit; pass 0 for the default of 500 MB.
func (*DiskCache) Get ¶
func (d *DiskCache) Get(key string) (io.ReadCloser, bool)
Get returns a reader for the cached data and true on hit, or nil and false on miss. The caller must close the returned reader.
type LoadOptions ¶
type LoadOptions struct {
// Headers are added to the HTTP request (e.g., authorization tokens).
Headers map[string]string
}
LoadOptions configures a single image load request.
type LoadResult ¶
type LoadResult struct {
// Image is the decoded image on success, nil on failure.
Image image.Image
// Err is the error on failure, nil on success.
Err error
}
LoadResult is the outcome of an image load operation.
type Loader ¶
type Loader struct {
// contains filtered or unexported fields
}
Loader coordinates fetching, decoding, and caching of network images. It deduplicates concurrent requests for the same URL. All methods are safe for concurrent use.
func DefaultLoader ¶
func DefaultLoader() *Loader
DefaultLoader returns the process-wide shared Loader. It uses a 100-entry / 100 MB in-memory cache and a 500 MB disk cache under the platform's cache directory. The loader is created lazily on first call.
func NewLoader ¶
func NewLoader(opts LoaderOptions) *Loader
NewLoader creates a Loader with the given options.
func (*Loader) ClearCache ¶
ClearCache clears both memory and disk caches. Memory cache clearing is always attempted; disk cache errors are returned.
func (*Loader) Evict ¶
Evict removes a URL from both memory and disk caches, including all header-variant entries that were cached for different request headers.
func (*Loader) Load ¶
func (l *Loader) Load(url string, opts LoadOptions, callback func(LoadResult)) (cancel func())
Load fetches, decodes, and caches an image from url. The callback is invoked from a background goroutine with either the decoded image or an error. Callers that need to update UI state should use drift.Dispatch inside the callback to marshal onto the UI thread.
If the image is already in the memory cache, the callback is called synchronously before Load returns and cancel is a no-op.
The returned function cancels this listener. If all listeners for a URL cancel, the underlying HTTP request is also canceled.
type LoaderOptions ¶
type LoaderOptions struct {
// MemoryCache is the in-memory LRU cache. Required.
MemoryCache *Cache
// DiskCache is the optional filesystem cache. Nil disables disk caching.
DiskCache *DiskCache
// Client is the HTTP client. Defaults to a client with 30s timeout.
Client *http.Client
}
LoaderOptions configures a Loader.
Source Files