1// Copyright (c) 2011 The Chromium Authors. All rights reserved.
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 "base/basictypes.h"
49#include "net/base/net_export.h"
50#include "net/disk_cache/blockfile/disk_format_base.h"
51
52namespace disk_cache {
53
54const int kIndexTablesize = 0x10000;
55const uint32 kIndexMagic = 0xC103CAC3;
56const uint32 kCurrentVersion = 0x20000;  // Version 2.0.
57
58struct LruData {
59  int32     pad1[2];
60  int32     filled;          // Flag to tell when we filled the cache.
61  int32     sizes[5];
62  CacheAddr heads[5];
63  CacheAddr tails[5];
64  CacheAddr transaction;     // In-flight operation target.
65  int32     operation;       // Actual in-flight operation.
66  int32     operation_list;  // In-flight operation list.
67  int32     pad2[7];
68};
69
70// Header for the master index file.
71struct NET_EXPORT_PRIVATE IndexHeader {
72  IndexHeader();
73
74  uint32      magic;
75  uint32      version;
76  int32       num_entries;   // Number of entries currently stored.
77  int32       num_bytes;     // Total size of the stored data.
78  int32       last_file;     // Last external file created.
79  int32       this_id;       // Id for all entries being changed (dirty flag).
80  CacheAddr   stats;         // Storage for usage data.
81  int32       table_len;     // Actual size of the table (0 == kIndexTablesize).
82  int32       crash;         // Signals a previous crash.
83  int32       experiment;    // Id of an ongoing test.
84  uint64      create_time;   // Creation time for this set of files.
85  int32       pad[52];
86  LruData     lru;           // Eviction control data.
87};
88
89// The structure of the whole index file.
90struct Index {
91  IndexHeader header;
92  CacheAddr   table[kIndexTablesize];  // Default size. Actual size controlled
93                                       // by header.table_len.
94};
95
96// Main structure for an entry on the backing storage. If the key is longer than
97// what can be stored on this structure, it will be extended on consecutive
98// blocks (adding 256 bytes each time), up to 4 blocks (1024 - 32 - 1 chars).
99// After that point, the whole key will be stored as a data block or external
100// file.
101struct EntryStore {
102  uint32      hash;               // Full hash of the key.
103  CacheAddr   next;               // Next entry with the same hash or bucket.
104  CacheAddr   rankings_node;      // Rankings node for this entry.
105  int32       reuse_count;        // How often is this entry used.
106  int32       refetch_count;      // How often is this fetched from the net.
107  int32       state;              // Current state.
108  uint64      creation_time;
109  int32       key_len;
110  CacheAddr   long_key;           // Optional address of a long key.
111  int32       data_size[4];       // We can store up to 4 data streams for each
112  CacheAddr   data_addr[4];       // entry.
113  uint32      flags;              // Any combination of EntryFlags.
114  int32       pad[4];
115  uint32      self_hash;          // The hash of EntryStore up to this point.
116  char        key[256 - 24 * 4];  // null terminated
117};
118
119COMPILE_ASSERT(sizeof(EntryStore) == 256, bad_EntyStore);
120const int kMaxInternalKeyLength = 4 * sizeof(EntryStore) -
121                                  offsetof(EntryStore, key) - 1;
122
123// Possible states for a given entry.
124enum EntryState {
125  ENTRY_NORMAL = 0,
126  ENTRY_EVICTED,    // The entry was recently evicted from the cache.
127  ENTRY_DOOMED      // The entry was doomed.
128};
129
130// Flags that can be applied to an entry.
131enum EntryFlags {
132  PARENT_ENTRY = 1,         // This entry has children (sparse) entries.
133  CHILD_ENTRY = 1 << 1      // Child entry that stores sparse data.
134};
135
136#pragma pack(push, 4)
137// Rankings information for a given entry.
138struct RankingsNode {
139  uint64      last_used;        // LRU info.
140  uint64      last_modified;    // LRU info.
141  CacheAddr   next;             // LRU list.
142  CacheAddr   prev;             // LRU list.
143  CacheAddr   contents;         // Address of the EntryStore.
144  int32       dirty;            // The entry is being modifyied.
145  uint32      self_hash;        // RankingsNode's hash.
146};
147#pragma pack(pop)
148
149COMPILE_ASSERT(sizeof(RankingsNode) == 36, bad_RankingsNode);
150
151}  // namespace disk_cache
152
153#endif  // NET_DISK_CACHE_BLOCKFILE_DISK_FORMAT_H_
154