// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef NET_DISK_CACHE_FLASH_SEGMENT_H_
#define NET_DISK_CACHE_FLASH_SEGMENT_H_

#include <vector>

#include "base/basictypes.h"
#include "base/gtest_prod_util.h"
#include "net/base/net_export.h"

namespace disk_cache {

class Storage;

// The underlying storage represented by Storage class, is divided into fixed
// size logical segments, represented by this class.  Since segment size is
// fixed, the storage size should be a multiple of segment size.  The picture
// below describes the relation between storage and segments:
//
//   |-----------+-----------+-----+-------------+-----------|
//   | segment 0 | segment 1 | ... | segment n-1 | segment n |
//   |-----------+-----------+-----+-------------+-----------|
//
//   |-------------------------------------------------------|
//   |                       storage                         |
//   |-------------------------------------------------------|
//
// A segment is constructed by taking its index within the storage, a flag
// indicating whether it is a read-only segment and a pointer to the storage on
// which it resides.  It provides an API for reading/writing entries residing on
// it.  Init() function must be called right after the construction of a segment
// and one should proceed to calling other functions only if Init() has
// succeeded.  After a successful initialization, one may proceed to call
// non-mutating functions; mutating functions can be called if the segment is
// not read-only.  Finally, Close() function must be called right before the
// destruction.  Calling Close() makes the segment immutable, which means
// mutating functions cannot be called on the object after that.
//
// Segment can only be used as a log, i.e. all writes are laid out sequentially
// on a segment.  As a result, WriteData() function does not take an offset.
// Current write offset can be learned by calling write_offset().
//
// Once the entries are written to the Segment and Close() called on it and the
// object destroyed, we should later be able to instantiate a read-only Segment
// object and recreate all the entries that were previously written to it.  To
// achieve this, a tiny region of Segment is used for its metadata and Segment
// provides two calls for interacting with metadata: StoreOffset() and
// GetOffsets().  The former can be used to store an offset that was returned by
// write_offset() and the latter can be used to retrieve all the offsets that
// were stored in the Segment.  Before attempting to write an entry, the client
// should call CanHold() to make sure that there is enough space in the segment.
//
// ReadData can be called over the range that was previously written with
// WriteData.  Reading from area that was not written will fail.

class NET_EXPORT_PRIVATE Segment {
 public:
  // |index| is the index of this segment on |storage|.  If the storage size is
  // X and the segment size is Y, where X >> Y and X % Y == 0, then the valid
  // values for the index are integers within the range [0, X/Y).  Thus, if
  // |index| is given value Z, then it covers bytes on storage starting at the
  // offset Z*Y and ending at the offset Z*Y+Y-1.
  Segment(int32 index, bool read_only, Storage* storage);
  ~Segment();

  int32 index() const { return index_; }
  int32 write_offset() const { return write_offset_; }

  bool HaveOffset(int32 offset) const;
  std::vector<int32> GetOffsets() const { return offsets_; }

  // Manage the number of users of this segment.
  void AddUser();
  void ReleaseUser();
  bool HasNoUsers() const;

  // Performs segment initialization.  Must be the first function called on the
  // segment and further calls should be made only if it is successful.
  bool Init();

  // Writes |size| bytes of data from |buffer| to segment, returns false if
  // fails and true if succeeds.  Can block for a long time.
  bool WriteData(const void* buffer, int32 size);

  // Reads |size| bytes of data living at |offset| into |buffer| returns true on
  // success and false on failure.
  bool ReadData(void* buffer, int32 size, int32 offset) const;

  // Stores the offset in the metadata.
  void StoreOffset(int32 offset);

  // Closes the segment, returns true on success and false on failure.  Closing
  // a segment makes it immutable.
  bool Close();

  // Returns true if segment can accommodate an entry of |size| bytes.
  bool CanHold(int32 size) const;

 private:
  int32 index_;
  int32 num_users_;
  bool read_only_;  // Indicates whether the segment can be written to.
  bool init_;  // Indicates whether segment was initialized.
  Storage* storage_;  // Storage on which the segment resides.
  const int32 offset_;  // Offset of the segment on |storage_|.
  const int32 summary_offset_;  // Offset of the segment summary.
  int32 write_offset_;  // Current write offset.
  std::vector<int32> offsets_;

  DISALLOW_COPY_AND_ASSIGN(Segment);
};

}  // namespace disk_cache

#endif  // NET_DISK_CACHE_FLASH_SEGMENT_H_