15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved.
25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be
35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file.
45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Defines the public interface of the disk cache. For more details see
65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// http://dev.chromium.org/developers/design-documents/network-stack/disk-cache
75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef NET_DISK_CACHE_DISK_CACHE_H_
95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define NET_DISK_CACHE_DISK_CACHE_H_
105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <string>
125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <vector>
135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/basictypes.h"
1503b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)#include "base/memory/ref_counted.h"
161320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "base/memory/scoped_ptr.h"
17eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#include "base/time/time.h"
185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/cache_type.h"
195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/completion_callback.h"
205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/net_export.h"
215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace base {
232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)class FilePath;
2403b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)class SingleThreadTaskRunner;
255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}
265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace net {
285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class IOBuffer;
295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NetLog;
305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}
315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace disk_cache {
335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Entry;
355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Backend;
365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Returns an instance of a Backend of the given |type|. |path| points to a
385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// folder where the cached data will be stored (if appropriate). This cache
395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// instance must be the only object that will be reading or writing files to
405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// that folder. The returned object should be deleted when not needed anymore.
415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// If |force| is true, and there is a problem with the cache initialization, the
425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// files will be deleted and a new set will be created. |max_bytes| is the
435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// maximum size the cache can grow to. If zero is passed in as |max_bytes|, the
445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// cache will determine the value to use. |thread| can be used to perform IO
455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// operations if a dedicated thread is required; a valid value is expected for
465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// any backend that performs operations on a disk. The returned pointer can be
475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// NULL if a fatal error is found. The actual return value of the function is a
485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// net error code. If this function returns ERR_IO_PENDING, the |callback| will
495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// be invoked when a backend is available or a fatal error condition is reached.
505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The pointer to receive the |backend| must remain valid until the operation
515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// completes (the callback is notified).
5203b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)NET_EXPORT int CreateCacheBackend(
5303b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    net::CacheType type,
5403b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    net::BackendType backend_type,
5503b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    const base::FilePath& path,
5603b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    int max_bytes,
5703b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    bool force,
5803b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    const scoped_refptr<base::SingleThreadTaskRunner>& thread,
5903b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    net::NetLog* net_log,
6003b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    scoped_ptr<Backend>* backend,
6103b57e008b61dfcb1fbad3aea950ae0e001748b0Torne (Richard Coles)    const net::CompletionCallback& callback);
625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The root interface for a disk cache instance.
645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NET_EXPORT Backend {
655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public:
665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  typedef net::CompletionCallback CompletionCallback;
675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
681320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci  class Iterator {
691320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci   public:
701320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    virtual ~Iterator() {}
711320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci
721320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // OpenNextEntry returns |net::OK| and provides |next_entry| if there is an
731320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // entry to enumerate. It returns |net::ERR_FAILED| at the end of
741320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // enumeration. If the function returns |net::ERR_IO_PENDING|, then the
751320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // final result will be passed to the provided |callback|, otherwise
761320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // |callback| will not be called. If any entry in the cache is modified
771320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // during iteration, the result of this function is thereafter undefined.
781320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    //
791320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // Calling OpenNextEntry after the backend which created it is destroyed
801320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // may fail with |net::ERR_FAILED|; however it should not crash.
811320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    //
821320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // Some cache backends make stronger guarantees about mutation during
831320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    // iteration, see top comment in simple_backend_impl.h for details.
841320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci    virtual int OpenNextEntry(Entry** next_entry,
851320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci                              const CompletionCallback& callback) = 0;
861320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci  };
871320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci
885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // If the backend is destroyed when there are operations in progress (any
895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // callback that has not been invoked yet), this method cancels said
905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // operations so the callbacks are not invoked, possibly leaving the work
915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // half way (for instance, dooming just a few entries). Note that pending IO
925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // for a given Entry (as opposed to the Backend) will still generate a
935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // callback from within this method.
945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual ~Backend() {}
955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns the type of this cache.
975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual net::CacheType GetCacheType() const = 0;
985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns the number of entries in the cache.
1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int32 GetEntryCount() const = 0;
1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Opens an existing entry. Upon success, |entry| holds a pointer to an Entry
1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // object representing the specified disk cache entry. When the entry pointer
1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // is no longer needed, its Close method should be called. The return value is
1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // a net error code. If this method returns ERR_IO_PENDING, the |callback|
1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // will be invoked when the entry is available. The pointer to receive the
1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // |entry| must remain valid until the operation completes.
1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int OpenEntry(const std::string& key, Entry** entry,
1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                        const CompletionCallback& callback) = 0;
1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Creates a new entry. Upon success, the out param holds a pointer to an
1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Entry object representing the newly created disk cache entry. When the
1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // entry pointer is no longer needed, its Close method should be called. The
1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // return value is a net error code. If this method returns ERR_IO_PENDING,
1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // the |callback| will be invoked when the entry is available. The pointer to
1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // receive the |entry| must remain valid until the operation completes.
1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int CreateEntry(const std::string& key, Entry** entry,
1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                          const CompletionCallback& callback) = 0;
1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Marks the entry, specified by the given key, for deletion. The return value
1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // is a net error code. If this method returns ERR_IO_PENDING, the |callback|
1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // will be invoked after the entry is doomed.
1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int DoomEntry(const std::string& key,
1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                        const CompletionCallback& callback) = 0;
1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Marks all entries for deletion. The return value is a net error code. If
1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // this method returns ERR_IO_PENDING, the |callback| will be invoked when the
1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // operation completes.
1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int DoomAllEntries(const CompletionCallback& callback) = 0;
1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Marks a range of entries for deletion. This supports unbounded deletes in
1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // either direction by using null Time values for either argument. The return
1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // value is a net error code. If this method returns ERR_IO_PENDING, the
1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // |callback| will be invoked when the operation completes.
135cedac228d2dd51db4b79ea1e72c7f249408ee061Torne (Richard Coles)  // Entries with |initial_time| <= access time < |end_time| are deleted.
1362a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  virtual int DoomEntriesBetween(base::Time initial_time,
1372a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)                                 base::Time end_time,
1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                                 const CompletionCallback& callback) = 0;
1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Marks all entries accessed since |initial_time| for deletion. The return
1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // value is a net error code. If this method returns ERR_IO_PENDING, the
1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // |callback| will be invoked when the operation completes.
143cedac228d2dd51db4b79ea1e72c7f249408ee061Torne (Richard Coles)  // Entries with |initial_time| <= access time are deleted.
1442a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  virtual int DoomEntriesSince(base::Time initial_time,
1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                               const CompletionCallback& callback) = 0;
1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1471320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci  // Returns an iterator which will enumerate all entries of the cache in an
1481320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci  // undefined order.
1491320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci  virtual scoped_ptr<Iterator> CreateIterator() = 0;
1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Return a list of cache statistics.
1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void GetStats(
1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)      std::vector<std::pair<std::string, std::string> >* stats) = 0;
1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Called whenever an external cache in the system reuses the resource
1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // referred to by |key|.
1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void OnExternalCacheHit(const std::string& key) = 0;
1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)};
1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This interface represents an entry in the disk cache.
1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NET_EXPORT Entry {
1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public:
1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  typedef net::CompletionCallback CompletionCallback;
1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  typedef net::IOBuffer IOBuffer;
1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Marks this cache entry for deletion.
1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void Doom() = 0;
1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Releases this entry. Calling this method does not cancel pending IO
1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // operations on this entry. Even after the last reference to this object has
1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // been released, pending completion callbacks may be invoked.
1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void Close() = 0;
1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns the key associated with this cache entry.
1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual std::string GetKey() const = 0;
1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns the time when this cache entry was last used.
1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual base::Time GetLastUsed() const = 0;
1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns the time when this cache entry was last modified.
1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual base::Time GetLastModified() const = 0;
1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns the size of the cache data with the given index.
1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int32 GetDataSize(int index) const = 0;
1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1862a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // Copies cached data into the given buffer of length |buf_len|. Returns the
1872a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // number of bytes read or a network error code. If this function returns
1882a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // ERR_IO_PENDING, the completion callback will be called on the current
1892a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // thread when the operation completes, and a reference to |buf| will be
1902a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // retained until the callback is called. Note that as long as the function
1912a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // does not complete immediately, the callback will always be invoked, even
1922a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // after Close has been called; in other words, the caller may close this
1932a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // entry without having to wait for all the callbacks, and still rely on the
1942a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // cleanup performed from the callback code.
1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int ReadData(int index, int offset, IOBuffer* buf, int buf_len,
1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                       const CompletionCallback& callback) = 0;
1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // Copies data from the given buffer of length |buf_len| into the cache.
1992a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // Returns the number of bytes written or a network error code. If this
2002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // function returns ERR_IO_PENDING, the completion callback will be called
2012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // on the current thread when the operation completes, and a reference to
2022a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // |buf| will be retained until the callback is called. Note that as long as
2032a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // the function does not complete immediately, the callback will always be
2042a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // invoked, even after Close has been called; in other words, the caller may
2052a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // close this entry without having to wait for all the callbacks, and still
2062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  // rely on the cleanup performed from the callback code.
2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // If truncate is true, this call will truncate the stored data at the end of
2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // what we are writing here.
2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int WriteData(int index, int offset, IOBuffer* buf, int buf_len,
2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                        const CompletionCallback& callback,
2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                        bool truncate) = 0;
2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Sparse entries support:
2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  //
2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // A Backend implementation can support sparse entries, so the cache keeps
2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // track of which parts of the entry have been written before. The backend
2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // will never return data that was not written previously, so reading from
2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // such region will return 0 bytes read (or actually the number of bytes read
2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // before reaching that region).
2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  //
2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // There are only two streams for sparse entries: a regular control stream
2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // (index 0) that must be accessed through the regular API (ReadData and
2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // WriteData), and one sparse stream that must me accessed through the sparse-
2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // aware API that follows. Calling a non-sparse aware method with an index
2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // argument other than 0 is a mistake that results in implementation specific
2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // behavior. Using a sparse-aware method with an entry that was not stored
2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // using the same API, or with a backend that doesn't support sparse entries
2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // will return ERR_CACHE_OPERATION_NOT_SUPPORTED.
2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  //
2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // The storage granularity of the implementation should be at least 1 KB. In
2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // other words, storing less than 1 KB may result in an implementation
2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // dropping the data completely, and writing at offsets not aligned with 1 KB,
2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // or with lengths not a multiple of 1 KB may result in the first or last part
2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // of the data being discarded. However, two consecutive writes should not
2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // result in a hole in between the two parts as long as they are sequential
2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // (the second one starts where the first one ended), and there is no other
2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // write between them.
2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  //
2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // The Backend implementation is free to evict any range from the cache at any
2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // moment, so in practice, the previously stated granularity of 1 KB is not
2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // as bad as it sounds.
2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  //
2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // The sparse methods don't support multiple simultaneous IO operations to the
2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // same physical entry, so in practice a single object should be instantiated
2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // for a given key at any given time. Once an operation has been issued, the
2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // caller should wait until it completes before starting another one. This
2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // requirement includes the case when an entry is closed while some operation
2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // is in progress and another object is instantiated; any IO operation will
2495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // fail while the previous operation is still in-flight. In order to deal with
2505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // this requirement, the caller could either wait until the operation
2515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // completes before closing the entry, or call CancelSparseIO() before closing
2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // the entry, and call ReadyForSparseIO() on the new entry and wait for the
2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // callback before issuing new operations.
2545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Behaves like ReadData() except that this method is used to access sparse
2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // entries.
2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int ReadSparseData(int64 offset, IOBuffer* buf, int buf_len,
2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                             const CompletionCallback& callback) = 0;
2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Behaves like WriteData() except that this method is used to access sparse
2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // entries. |truncate| is not part of this interface because a sparse entry
2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // is not expected to be reused with new data. To delete the old data and
2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // start again, or to reduce the total size of the stream data (which implies
2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // that the content has changed), the whole entry should be doomed and
2655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // re-created.
2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int WriteSparseData(int64 offset, IOBuffer* buf, int buf_len,
2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                              const CompletionCallback& callback) = 0;
2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns information about the currently stored portion of a sparse entry.
2705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // |offset| and |len| describe a particular range that should be scanned to
2715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // find out if it is stored or not. |start| will contain the offset of the
2725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // first byte that is stored within this range, and the return value is the
2735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // minimum number of consecutive stored bytes. Note that it is possible that
2745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // this entry has stored more than the returned value. This method returns a
2755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // net error code whenever the request cannot be completed successfully. If
2765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // this method returns ERR_IO_PENDING, the |callback| will be invoked when the
2775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // operation completes, and |start| must remain valid until that point.
2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int GetAvailableRange(int64 offset, int len, int64* start,
2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                                const CompletionCallback& callback) = 0;
2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns true if this entry could be a sparse entry or false otherwise. This
2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // is a quick test that may return true even if the entry is not really
2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // sparse. This method doesn't modify the state of this entry (it will not
2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // create sparse tracking data). GetAvailableRange or ReadSparseData can be
2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // used to perform a definitive test of whether an existing entry is sparse or
2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // not, but that method may modify the current state of the entry (making it
2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // sparse, for instance). The purpose of this method is to test an existing
2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // entry, but without generating actual IO to perform a thorough check.
2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual bool CouldBeSparse() const = 0;
2905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Cancels any pending sparse IO operation (if any). The completion callback
2925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // of the operation in question will still be called when the operation
2935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // finishes, but the operation will finish sooner when this method is used.
2945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void CancelSparseIO() = 0;
2955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
2965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Returns OK if this entry can be used immediately. If that is not the
2975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // case, returns ERR_IO_PENDING and invokes the provided callback when this
2985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // entry is ready to use. This method always returns OK for non-sparse
2995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // entries, and returns ERR_IO_PENDING when a previous operation was cancelled
3005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // (by calling CancelSparseIO), but the cache is still busy with it. If there
3015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // is a pending operation that has not been cancelled, this method will return
3025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // OK although another IO operation cannot be issued at this time; in this
3035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // case the caller should just wait for the regular callback to be invoked
3045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // instead of using this method to provide another callback.
3055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  //
3065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Note that CancelSparseIO may have been called on another instance of this
3075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // object that refers to the same physical disk entry.
3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Note: This method is deprecated.
3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual int ReadyForSparseIO(const CompletionCallback& callback) = 0;
3105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
3115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) protected:
3125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual ~Entry() {}
3135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)};
3145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
315bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdochstruct EntryDeleter {
316bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch  void operator()(Entry* entry) {
317bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch    // Note that |entry| is ref-counted.
318bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch    entry->Close();
319bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch  }
320bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch};
321bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch
322bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch// Automatically closes an entry when it goes out of scope.
323bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdochtypedef scoped_ptr<Entry, EntryDeleter> ScopedEntryPtr;
324bbcdd45c55eb7c4641ab97aef9889b0fc828e7d3Ben Murdoch
3255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}  // namespace disk_cache
3265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
3275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif  // NET_DISK_CACHE_DISK_CACHE_H_