1 // Copyright 2011 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 // The cache is stored on disk as a collection of block-files, plus an index 6 // file plus a collection of external files. 7 // 8 // Any data blob bigger than kMaxBlockSize (disk_cache/addr.h) will be stored in 9 // a separate file named f_xxx where x is a hexadecimal number. Shorter data 10 // will be stored as a series of blocks on a block-file. In any case, CacheAddr 11 // represents the address of the data inside the cache. 12 // 13 // The index file is just a simple hash table that maps a particular entry to 14 // a CacheAddr value. Linking for a given hash bucket is handled internally 15 // by the cache entry. 16 // 17 // The last element of the cache is the block-file. A block file is a file 18 // designed to store blocks of data of a given size. For more details see 19 // disk_cache/disk_format_base.h 20 // 21 // A new cache is initialized with four block files (named data_0 through 22 // data_3), each one dedicated to store blocks of a given size. The number at 23 // the end of the file name is the block file number (in decimal). 24 // 25 // There are two "special" types of blocks: an entry and a rankings node. An 26 // entry keeps track of all the information related to the same cache entry, 27 // such as the key, hash value, data pointers etc. A rankings node keeps track 28 // of the information that is updated frequently for a given entry, such as its 29 // location on the LRU lists, last access time etc. 30 // 31 // The files that store internal information for the cache (blocks and index) 32 // are at least partially memory mapped. They have a location that is signaled 33 // every time the internal structures are modified, so it is possible to detect 34 // (most of the time) when the process dies in the middle of an update. 35 // 36 // In order to prevent dirty data to be used as valid (after a crash), every 37 // cache entry has a dirty identifier. Each running instance of the cache keeps 38 // a separate identifier (maintained on the "this_id" header field) that is used 39 // to mark every entry that is created or modified. When the entry is closed, 40 // and all the data can be trusted, the dirty flag is cleared from the entry. 41 // When the cache encounters an entry whose identifier is different than the one 42 // being currently used, it means that the entry was not properly closed on a 43 // previous run, so it is discarded. 44 45 #ifndef NET_DISK_CACHE_BLOCKFILE_DISK_FORMAT_H_ 46 #define NET_DISK_CACHE_BLOCKFILE_DISK_FORMAT_H_ 47 48 #include <stddef.h> 49 #include <stdint.h> 50 #include <string.h> 51 52 #include "net/base/net_export.h" 53 #include "net/disk_cache/blockfile/disk_format_base.h" 54 55 namespace disk_cache { 56 57 const int kIndexTablesize = 0x10000; 58 const uint32_t kIndexMagic = 0xC103CAC3; 59 const uint32_t kVersion2_0 = 0x20000; 60 const uint32_t kVersion2_1 = 0x20001; 61 const uint32_t kVersion3_0 = 0x30000; 62 const uint32_t kCurrentVersion = kVersion3_0; 63 64 struct LruData { 65 int32_t pad1[2]; 66 int32_t filled; // Flag to tell when we filled the cache. 67 int32_t sizes[5]; 68 CacheAddr heads[5]; 69 CacheAddr tails[5]; 70 CacheAddr transaction; // In-flight operation target. 71 int32_t operation; // Actual in-flight operation. 72 int32_t operation_list; // In-flight operation list. 73 int32_t pad2[7]; 74 }; 75 76 // Header for the master index file. 77 struct NET_EXPORT_PRIVATE IndexHeader { 78 IndexHeader(); 79 80 uint32_t magic; 81 uint32_t version; 82 int32_t num_entries; // Number of entries currently stored. 83 int32_t old_v2_num_bytes; // Total size of the stored data, in versions 2.x 84 int32_t last_file; // Last external file created. 85 int32_t this_id; // Id for all entries being changed (dirty flag). 86 CacheAddr stats; // Storage for usage data. 87 int32_t table_len; // Actual size of the table (0 == kIndexTablesize). 88 int32_t crash; // Signals a previous crash. 89 int32_t experiment; // Id of an ongoing test. 90 uint64_t create_time; // Creation time for this set of files. 91 int64_t num_bytes; // Total size of the stored data, in version 3.0 92 int32_t pad[50]; 93 LruData lru; // Eviction control data. 94 }; 95 96 // The structure of the whole index file. 97 struct Index { 98 IndexHeader header; 99 CacheAddr table[kIndexTablesize]; // Default size. Actual size controlled 100 // by header.table_len. 101 }; 102 103 // Main structure for an entry on the backing storage. If the key is longer than 104 // what can be stored on this structure, it will be extended on consecutive 105 // blocks (adding 256 bytes each time), up to 4 blocks (1024 - 32 - 1 chars). 106 // After that point, the whole key will be stored as a data block or external 107 // file. 108 struct EntryStore { 109 uint32_t hash; // Full hash of the key. 110 CacheAddr next; // Next entry with the same hash or bucket. 111 CacheAddr rankings_node; // Rankings node for this entry. 112 int32_t reuse_count; // How often is this entry used. 113 int32_t refetch_count; // How often is this fetched from the net. 114 int32_t state; // Current state. 115 uint64_t creation_time; 116 int32_t key_len; 117 CacheAddr long_key; // Optional address of a long key. 118 int32_t data_size[4]; // We can store up to 4 data streams for each 119 CacheAddr data_addr[4]; // entry. 120 uint32_t flags; // Any combination of EntryFlags. 121 int32_t pad[4]; 122 uint32_t self_hash; // The hash of EntryStore up to this point. 123 char key[256 - 24 * 4]; // null terminated 124 }; 125 126 static_assert(sizeof(EntryStore) == 256, "bad EntryStore"); 127 const int kMaxInternalKeyLength = 4 * sizeof(EntryStore) - 128 offsetof(EntryStore, key) - 1; 129 130 // Possible states for a given entry. 131 enum EntryState { 132 ENTRY_NORMAL = 0, 133 ENTRY_EVICTED, // The entry was recently evicted from the cache. 134 ENTRY_DOOMED // The entry was doomed. 135 }; 136 137 // Flags that can be applied to an entry. 138 enum EntryFlags { 139 PARENT_ENTRY = 1, // This entry has children (sparse) entries. 140 CHILD_ENTRY = 1 << 1 // Child entry that stores sparse data. 141 }; 142 143 #pragma pack(push, 4) 144 // Rankings information for a given entry. 145 struct RankingsNode { 146 uint64_t last_used; // LRU info. 147 uint64_t last_modified; // LRU info. 148 CacheAddr next; // LRU list. 149 CacheAddr prev; // LRU list. 150 CacheAddr contents; // Address of the EntryStore. 151 int32_t dirty; // The entry is being modifyied. 152 uint32_t self_hash; // RankingsNode's hash. 153 }; 154 #pragma pack(pop) 155 156 static_assert(sizeof(RankingsNode) == 36, "bad RankingsNode"); 157 158 } // namespace disk_cache 159 160 #endif // NET_DISK_CACHE_BLOCKFILE_DISK_FORMAT_H_ 161