An object that maps URL requests to cached response objects.


class URLCache : NSObject


The URLCache class implements the caching of responses to URL load requests, by mapping NSURLRequest objects to CachedURLResponse objects. It provides a composite in-memory and on-disk cache, and lets you manipulate the sizes of both the in-memory and on-disk portions. You can also control the path where cache data is persistently stored.

Thread Safety

In iOS 8 and later, and macOS 10.10 and later, URLCache is thread safe.

Although URLCache instance methods can safely be called from multiple execution contexts at the same time, be aware that methods like cachedResponse(for:) and storeCachedResponse(_:for:) have an unavoidable race condition when attempting to read or write responses for the same request.

Subclasses of URLCache must implement overridden methods in such a thread-safe manner.

Subclassing Notes

The URLCache class is meant to be used as-is, but you can subclass it when you have specific needs. For example, you might want to screen which responses are cached, or reimplement the storage mechanism for security or other reasons.

When overriding methods of this class, be aware that methods that take a task parameter are preferred by the system to those that do not. Therefore, you should override the task-based methods when subclassing, as follows:


Getting and Setting Shared Cache

class var shared: URLCache

The shared URL cache instance.

Creating a New Cache Object

init(memoryCapacity: Int, diskCapacity: Int, directory: URL?)

Creates a URL cache object with the specified memory and disk capacities, in the specified directory.

init(memoryCapacity: Int, diskCapacity: Int, diskPath: String?)

Creates a URL cache object with the specified values.


Getting and Storing Cached Objects

func cachedResponse(for: URLRequest) -> CachedURLResponse?

Returns the cached URL response in the cache for the specified URL request.

func storeCachedResponse(CachedURLResponse, for: URLRequest)

Stores a cached URL response for a specified request.

func getCachedResponse(for: URLSessionDataTask, completionHandler: (CachedURLResponse?) -> Void)

Gets the cached URL response for a data task, passing it to the provided completion handler.

func storeCachedResponse(CachedURLResponse, for: URLSessionDataTask)

Stores a cached URL response for a specified data task.

Removing Cached Objects

func removeCachedResponse(for: URLRequest)

Removes the cached URL response for a specified URL request.

func removeCachedResponse(for: URLSessionDataTask)

Removes the cached URL response for a specified data task.

func removeCachedResponses(since: Date)

Clears the given cache of any cached responses since the provided date.

func removeAllCachedResponses()

Clears the receiver’s cache, removing all stored cached URL responses.

Getting and Setting On-disk Cache Properties

var currentDiskUsage: Int

The current size of the on-disk cache, in bytes.

var diskCapacity: Int

The capacity of the on-disk cache, in bytes.

Getting and Setting In-memory Cache Properties

var currentMemoryUsage: Int

The current size of the in-memory cache, in bytes.

var memoryCapacity: Int

The capacity of the in-memory cache, in bytes.

Cache Storage Policies

enum URLCache.StoragePolicy

These constants specify the caching strategy used by an CachedURLResponse object.


Inherits From

Conforms To

See Also

Cache Behavior

Accessing Cached Data

Control how URL requests make use of previously cached data.

class CachedURLResponse

A cached response to a URL request.