Package icyllis.arc3d.engine

# Class ResourceCache

java.lang.Object
icyllis.arc3d.engine.ResourceCache

@NotThreadSafe public final class ResourceCache extends Object
Manages the lifetime of all `Resource` instances.

Resources may optionally have two types of keys:

1. Scratch key. This is for resources whose allocations are cached but not their contents. Multiple resources can share the same scratch key. This is so a caller can have two resource instances with the same properties (e.g. multi-pass rendering that ping-pongs between two temporary surfaces). The scratch key is set at resource creation time and should never change. Resources need not have a scratch key.
2. Unique key. This key's meaning is specific to the domain that created the key. Only one resource may have a given unique key. The unique key can be set, cleared, or changed anytime after resource creation.

A unique key always takes precedence over a shared key when a resource has both types of keys. If a resource has neither key type then it will be deleted as soon as the last reference to it is dropped.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Resource`
  `findAndRefResource(IResourceKey key, boolean budgeted)`
  Find a resource that matches a key.
  `long`
  `getBudgetedBytes()`
  Returns the number of bytes consumed by budgeted resources.
  `int`
  `getBudgetedResourceCount()`
  Returns the number of resources that count against the budget.
  `long`
  `getMaxBudget()`
  Returns the number of bytes that cached resources should count against.
  `long`
  `getPurgeableBytes()`
  Returns the number of bytes held by unlocked resources which are available for cleanup.
  `int`
  `getResourceCount()`
  Returns the number of cached resources.
  `void`
  `insertResource(Resource resource)`
  `boolean`
  `processReturnedResources()`
  `void`
  `purgeAsNeeded()`
  Performs any pending maintenance operations needed by the cache.
  `void`
  `purgeResources()`
  Deallocates unlocked resources as much as possible.
  `void`
  `purgeResourcesNotUsedSince(long timeMillis)`
  Deallocates unlocked resources not used since the passed point in time.
  `void`
  `setMaxBudget(long maxBytes)`
  Sets the max GPU memory byte size of the cache.
  `void`
  `setSurfaceProvider(ImageProxyCache imageProxyCache)`
  `void`
  `setThreadSafeCache(ThreadSafeCache threadSafeCache)`
  `void`
  `shutdown()`
  Called by the ResourceProvider when it is dropping its ref to the ResourceCache.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### setMaxBudget

    @VisibleForTesting public void setMaxBudget(long maxBytes)
    Sets the max GPU memory byte size of the cache. A `purgeAsNeeded()` is followed by this method call. The passed value can be retrieved by `getMaxBudget()`.

  - ### getResourceCount

    public int getResourceCount()
    Returns the number of cached resources.

  - ### getBudgetedResourceCount

    public int getBudgetedResourceCount()
    Returns the number of resources that count against the budget.

  - ### getBudgetedBytes

    public long getBudgetedBytes()
    Returns the number of bytes consumed by budgeted resources.

  - ### getPurgeableBytes

    public long getPurgeableBytes()
    Returns the number of bytes held by unlocked resources which are available for cleanup.

  - ### getMaxBudget

    public long getMaxBudget()
    Returns the number of bytes that cached resources should count against. This can be changed by `setMaxBudget(long)`.

  - ### shutdown

    public void shutdown()
    Called by the ResourceProvider when it is dropping its ref to the ResourceCache. After this is called no more Resources can be returned to the ResourceCache (besides those already in the return queue). Also no new Resources can be retrieved from the ResourceCache.

  - ### findAndRefResource

    @Nullable public Resource findAndRefResource(@Nonnull IResourceKey key, boolean budgeted)
    Find a resource that matches a key.

  - ### setSurfaceProvider

    public void setSurfaceProvider(ImageProxyCache imageProxyCache)

  - ### setThreadSafeCache

    public void setThreadSafeCache(ThreadSafeCache threadSafeCache)

  - ### purgeAsNeeded

    @VisibleForTesting public void purgeAsNeeded()
    Performs any pending maintenance operations needed by the cache. In particular, deallocates resources to become under budget and processes resources with invalidated unique keys.

  - ### purgeResources

    public void purgeResources()
    Deallocates unlocked resources as much as possible. All purgeable resources will be deleted.

  - ### purgeResourcesNotUsedSince

    public void purgeResourcesNotUsedSince(long timeMillis)
    Deallocates unlocked resources not used since the passed point in time. The time-base is `System.currentTimeMillis()`. Otherwise, all purgeable resources older than `timeMillis` will be deleted.
    Parameters:
      `timeMillis` - the resources older than this time will be deleted

  - ### processReturnedResources

    @VisibleForTesting public boolean processReturnedResources()

  - ### insertResource

    public void insertResource(@Nonnull Resource resource)