class EE::UI::WebResourceCache¶

Overview¶

Shared HTTP-backed document resource cache. More…

#include <webresourcecache.hpp>

class WebResourceCache: public std::enable_shared_from_this< WebResourceCache > {
public:
    // typedefs

    typedef std::function<void(const WebResourceResult&)> Callback;
    typedef std::function<void(Network::Http::Response)> FetchCompletion;
    typedef std::function<void(const WebResourceRequest&, FetchCompletion)> Fetcher;

    // construction

    ~WebResourceCache();

    // methods

    static WebResourceCachePtr New();
    CachePartitionId createPartition();
    DocumentSessionId createSession(CachePartitionId partition = 0);
    void destroySession(DocumentSessionId session);
    Uint64 beginNavigation(DocumentSessionId session, const Network::URI& uri);
    Uint64 getSessionGeneration(DocumentSessionId session) const;
    CachePartitionId getSessionPartition(DocumentSessionId session) const;
    void requestData(DocumentSessionId session, Uint64 generation, WebResourceRequest request, Callback callback);
    Graphics::TexturePtr requestTexture(DocumentSessionId session, Uint64 generation, WebResourceRequest request, Callback callback = {});
    void setTTL(System::Time ttl);
    System::Time getTTL() const;
    void setRetryDelay(System::Time delay);
    System::Time getRetryDelay() const;
    void setByteBudget(std::size_t bytes);
    std::size_t getByteBudget() const;
    std::size_t getRetainedBytes() const;
    std::size_t getEntryCount() const;
    std::size_t getInFlightCount() const;
    void prune();
    void clear();
    void setFetcher(Fetcher fetcher);
};

Detailed Documentation¶

Shared HTTP-backed document resource cache.

The cache separates three concepts:

A partition defines which HTTP/cookie context may share entries.
A session represents one active document using entries from that partition.
A navigation generation prevents an obsolete document from receiving asynchronous results.

Entries are strongly retained by the cache after their final document lease is released. Their TTL starts at that release point, allowing Back/Forward navigation to reuse them. Expired entries are removed by prune(); UIWebView invokes it periodically. A byte budget additionally evicts the least-recently-used unleased entries. Active leases and in-flight loads are not evicted.

Requests for the same key are coalesced into one HTTP operation. Each current subscriber receives the result, while callbacks belonging to obsolete navigation generations are discarded. Public operations are internally synchronized. Subscriber callbacks run without the cache mutex held.

Typedefs¶

typedef std::function<void(const WebResourceResult&)> Callback

Receives the completed result of a data or texture request.

typedef std::function<void(Network::Http::Response)> FetchCompletion

Completion supplied to a custom Fetcher.

typedef std::function<void(const WebResourceRequest&, FetchCompletion)> Fetcher

Custom fetch implementation, primarily intended for deterministic tests.

The fetcher must eventually invoke FetchCompletion exactly once. Production uses Http::requestAsync when no custom fetcher is installed.

Construction¶

~WebResourceCache()

Cancels cache delivery and releases all retained entries and sessions.

Methods¶

static WebResourceCachePtr New()

Returns:

A newly allocated shared web-resource cache.

CachePartitionId createPartition()

Allocates a new process-wide partition identifier.

Returns:

An opaque, non-zero partition ID.

DocumentSessionId createSession(CachePartitionId partition = 0)

Creates a document session.

Parameters:

partition

Partition to join. Zero creates a new private partition.

Returns:

An opaque, non-zero document session ID.

void destroySession(DocumentSessionId session)

Destroys a session and releases all entries leased by it.

Releasing the final lease starts each entry’s TTL; it does not normally erase entries immediately. Pending callbacks for the destroyed session will not be delivered.

Uint64 beginNavigation(DocumentSessionId session, const Network::URI& uri)

Begins a new document navigation in an existing session.

Previous document leases are released and the generation is incremented. Pending subscribers from older generations become stale, but shared in-flight requests continue for other current subscribers.

Parameters:

session	Session performing the navigation.
uri	Destination document URI, used to record its origin.

Returns:

The new generation, or zero when the session does not exist.

Uint64 getSessionGeneration(DocumentSessionId session) const

Returns:

The current generation for a session, or zero when it does not exist.

CachePartitionId getSessionPartition(DocumentSessionId session) const

Returns:

The partition used by a session, or zero when it does not exist.

void requestData(DocumentSessionId session, Uint64 generation, WebResourceRequest request, Callback callback)

Requests a document, stylesheet, font, or other non-texture response body.

A ready cache hit may invoke callback synchronously. A miss starts or joins an asynchronous fetch. The callback is omitted when the session/generation is stale.

Parameters:

session	Requesting document session.
generation	Generation returned by beginNavigation().
request	Resource and transport description.
callback	Optional completion callback.

Graphics::TexturePtr requestTexture(DocumentSessionId session, Uint64 generation, WebResourceRequest request, Callback callback = {})

Requests an image as a shared texture.

On a miss, this creates and returns a transparent placeholder immediately. The same TexturePtr is populated after download and decode. A ready hit returns the existing texture without a new HTTP request. This function must be called where texture creation is valid, and the request must provide an appropriate completionDispatcher for asynchronous GPU upload.

Returns:

The cached/new texture, or null for an invalid or stale session.

void setTTL(System::Time ttl)

Sets the retention duration used when an entry’s final document lease is released.

System::Time getTTL() const

Returns:

The current post-lease retention duration.

void setRetryDelay(System::Time delay)

Sets how long a failed entry suppresses another fetch attempt.

System::Time getRetryDelay() const

Returns:

The current failed-request retry delay.

void setByteBudget(std::size_t bytes)

Sets the maximum retained response/texture byte estimate.

Applying a smaller budget immediately evicts least-recently-used unleased entries where possible. Active entries may temporarily make retained bytes exceed the budget.

std::size_t getByteBudget() const

Returns:

The configured retained-byte budget.

std::size_t getRetainedBytes() const

Returns:

Estimated bytes retained by ready data bodies and decoded image textures.

std::size_t getEntryCount() const

Returns:

Number of cache entries in all states and partitions.

std::size_t getInFlightCount() const

clear() resets this count even though invalidated underlying operations may still finish; those stale completions are ignored and do not alter the count.

Returns:

Number of HTTP requests belonging to the cache’s current epoch.

void prune()

Removes expired entries and enforces the byte budget.

Active document leases and loading entries are preserved. UIWebView calls this periodically; other cache owners should provide their own maintenance point.

void clear()

Removes every entry immediately and suppresses delivery from outstanding fetches.

Sessions remain valid but no longer lease entries. This does not cancel the underlying HTTP operation. A late completion is ignored using its operation identity, including when a new request has already recreated an entry with the same cache key.

void setFetcher(Fetcher fetcher)

Installs or clears a custom HTTP fetch implementation.