1# disk_cache API 2 3The disk_cache API provides for caches that can store multiple random-access 4byte streams of data associated with a key on disk (or in memory). 5 6There are two kinds of entries that can be stored: regular and sparse. 7 8Regular entries contain up to 3 separate data streams. Usually stream 0 9would be used for some kind of primary small metadata (e.g. HTTP headers); 10stream 1 would contain the main payload (e.g. HTTP body); and stream 2 would 11optionally contain some auxiliary metadata that's needed only some of the time 12(e.g. V8 compilation cache). There is no requirement that these streams be used 13in this way, but implementations may expect similar size and usage 14characteristics. 15 16Sparse entries have a stream 0 and a separate sparse stream that's accessed with 17special methods that have `Sparse` in their names. It's an API misuse to try to 18access streams 1 or 2 of sparse entries or to call `WriteSparseData` on entries 19that have contents in those streams. Calling `SparseReadData` or 20`GetAvailableRange` to check whether entries are sparse is, however, permitted. 21An added entry becomes a regular entry once index 1 or 2 is written to, or it 22becomes a sparse entry once the sparse stream is written to. Once that is done, 23it cannot change type and the access/modification restrictions relevant to the 24type apply. Type of an entry can always be determined using `SparseReadData` or 25`GetAvailableRange`. 26 27The sparse streams are named as such because they are permitted to have holes in 28the byte ranges of contents they represent (and implementations may also drop 29some pieces independently). For example, in the case of a regular entry, 30starting with an empty entry, and performing `WriteData` on some stream at 31offset = 1024, length = 1024, then another `WriteData` at offset = 3072, 32length = 1024, results in the stream having length = 4096, and the areas not 33written to filled in with zeroes. 34 35In contrast, after the same sequence of `WriteSparseData` operations, the entry 36will actually keep track that [1024, 2048) and [3072, 4096) are valid, and will 37permit queries with `GetAvailableRange`, and only allow reads of the defined 38ranges. 39 40[`net/disk_cache/disk_cache.h`](/net/disk_cache/disk_cache.h) is the only 41include you need if you just want to use this API. 42`disk_cache::CreateCacheBackend()` is the first method you'll need to call. 43 44[TOC] 45 46## The implementations 47 48### [disk_cache/blockfile directory](/net/disk_cache/blockfile/) 49 50This implementation backs the HTTP cache on Windows. It tries to pack 51many small entries caches typically have into "block" files, which can help 52performance but introduces a lot of complexity and makes recovery from 53corruption very tricky. 54 55### [disk_cache/memory directory](/net/disk_cache/memory/) 56 57This contains the in-memory-only implementation. It's used for incognito 58mode. 59 60### [disk_cache/simple directory](/net/disk_cache/simple/) 61 62This implementation backs the HTTP cache on Android, ChromeOS, and Linux, 63macOS and is used to implement some features like CacheStorage on all platforms. 64The design is centered around roughly having a single file per cache entry (more 65precisely for streams 0 and 1), with a compact and simple in-memory index for 66membership tests, which makes it very robust against failures, but also highly 67sensitive to OS file system performance. 68