Rename Vol to Stripe (#10666)

* Rename struct Vol to Stripe

* Fix clang-format

* Fix docs

* Rename DiskVol to DiskStripe

* Fix comments

doc/developer-guide/cache-architecture/architecture.en.rst

@@ -126,7 +126,7 @@ span of bytes. Internally each stripe is treated almost entirely independently.
 The data structures described in this section are duplicated for each stripe.
 
 Internally the term *volume* is used for these stripes and implemented primarily
-in :cpp:class:`Vol`. What a user thinks of as a volume (and what this document
+in :cpp:class:`Stripe`. What a user thinks of as a volume (and what this document
 calls a *cache volume*) is represented by :cpp:class:`CacheVol`.
 
 .. note::
@@ -259,7 +259,7 @@ Storage Layout
 The storage layout is the stripe metadata followed by cached content. The
 metadata consists of three parts: the stripe header, the directory, and the
 stripe footer. The metadata is stored twice. The header and the footer are
-instances of :cpp:class:`VolHeaderFooter`. This is a stub structure which can
+instances of :cpp:class:`StripeHeaderFooter`. This is a stub structure which can
 have a trailing variable sized array. This array is used as the segment free
 list roots in the directory. Each contains the segment index of the first
 element of the free list for the segment. The footer is a copy of the header
@@ -280,26 +280,26 @@ start
    The offset for the start of the content, after the stripe metadata.
 
 length
-   Total number of bytes in the stripe. :cpp:member:`Vol::len`.
+   Total number of bytes in the stripe. :cpp:member:`Stripe::len`.
 
 data length
    Total number of blocks in the stripe available for content storage.
-   :cpp:member:`Vol::data_blocks`.
+   :cpp:member:`Stripe::data_blocks`.
 
 .. note::
 
    Great care must be taken with sizes and lengths in the cache code because
    there are at least three different metrics (bytes, cache blocks, store
    blocks) used in various places.
 
-The header for a stripe is a variably sized instance of :class:`VolHeaderFooter`.
+The header for a stripe is a variably sized instance of :class:`StripeHeaderFooter`.
 The variable trailing section contains the head indices of the directory entry
 free lists for the segments.
 
 .. figure:: images/stripe-header.svg
    :align: center
 
-The trailing :member:`VolHeaderFooter::freelist` array overlays the disk storage with
+The trailing :member:`StripeHeaderFooter::freelist` array overlays the disk storage with
 an entry for every segment, even though the array is declared to have length `1`.
 Each free list entry is a 16 bit value that is the index of the first directory entry
 in the free list for that segment. E.g. :code:`freelist[4]` is the index of the
@@ -505,7 +505,7 @@ Disk Failure
 
 The cache is designed to be relatively resistant to disk failures. Because each
 :term:`storage unit` in each :term:`cache volume` is mostly independent, the
-loss of a disk simply means that the corresponding :cpp:class:`Vol` instances
+loss of a disk simply means that the corresponding :cpp:class:`Stripe` instances
 (one per cache volume that uses the storage unit) becomes unusable. The primary
 issue is updating the volume assignment table to both preserve assignments for
 objects on still operational volumes while distributing the assignments from the
@@ -778,7 +778,7 @@ The basic steps to a cache lookup are:
 
 #. The cache stripe is determined (based on the cache key).
 
-   The :term:`cache key` is used as a hash key in to an array of :cpp:class:`Vol` instances by
+   The :term:`cache key` is used as a hash key in to an array of :cpp:class:`Stripe` instances by
    :func:`Cache::key_to_vol`. The construction and arrangement of this array is the essence of how
    volumes are assigned.
 
@@ -939,7 +939,7 @@ Aggregation Buffer
 ------------------
 
 Disk writes to cache are handled through an *aggregation buffer*. There is one
-for each :cpp:class:`Vol` instance. To minimize the number of system calls data
+for each :cpp:class:`Stripe` instance. To minimize the number of system calls data
 is written to disk in units of roughly :ref:`target fragment size <target-fragment-size>`
 bytes. The algorithm used is simple: data is piled up in the aggregation buffer
 until no more will fit without going over the target fragment size, at which
@@ -974,11 +974,11 @@ In some cases this is not acceptable and the object is *evacuated* by reading
 it from the cache and then writing it back to cache which moves the physical
 storage of the object from in front of the write cursor to behind the write
 cursor. Objects that are evacuated are handled in this way based on data in
-stripe data structures (attached to the :cpp:class:`Vol` instance).
+stripe data structures (attached to the :cpp:class:`Stripe` instance).
 
 Evacuation data structures are defined by dividing up the volume content into
 a disjoint and contiguous set of regions of ``EVACUATION_BUCKET_SIZE`` bytes.
-The :cpp:member:`Vol::evacuate` member is an array with an element for each
+The :cpp:member:`Stripe::evacuate` member is an array with an element for each
 evacuation region. Each element is a doubly linked list of :cpp:class:`EvacuationBlock`
 instances. Each instance contains a :cpp:class:`Dir` that specifies the fragment
 to evacuate. It is assumed that an evacuation block is placed in the evacuation
@@ -1004,14 +1004,14 @@ if the count goes to zero. If the ``EvacuationBlock`` already exists with a
 count of zero, the count is not modified and the number of readers is not
 tracked, so the evacuation is valid as long as the object exists.
 
-Evacuation is driven by cache writes, essentially in :cpp:member:`Vol::aggWrite`.
+Evacuation is driven by cache writes, essentially in :cpp:member:`Stripe::aggWrite`.
 This method processes the pending cache virtual connections that are trying to
 write to the stripe. Some of these may be evacuation virtual connections. If so
 then the completion callback for that virtual connection is called as the data
 is put in to the aggregation buffer.
 
 When no more cache virtual connections can be processed (due to an empty queue
-or the aggregation buffer filling) then :cpp:member:`Vol::evac_range` is called
+or the aggregation buffer filling) then :cpp:member:`Stripe::evac_range` is called
 to clear the range to be overwritten plus an additional :c:macro:`EVACUATION_SIZE`
 range. The buckets covering that range are checked. If there are any items in
 the buckets a new cache virtual connection (a *doc evacuator*) is created and
@@ -1021,7 +1021,7 @@ the read completes it is checked for validity and if valid, the cache virtual
 connection for it is placed at the front of the write queue for the stripe and
 the write aggregation resumed.
 
-Before doing a write, the method :cpp:member:`Vol::evac_range()` is called to
+Before doing a write, the method :cpp:member:`Stripe::evac_range()` is called to
 start an evacuation. If any fragments are found in the buckets in the range the
 earliest such fragment (smallest offset, closest to the write cursor) is
 selected and read from disk and the aggregation buffer write is suspended. The

doc/developer-guide/cache-architecture/core-cache-functions.en.rst

@@ -96,7 +96,7 @@ Core Cache Types
 Core Cache Functions
 ====================
 
-.. cpp:function:: int dir_probe(const CacheKey * key, Vol * d, Dir * result, Dir ** last_collision)
+.. cpp:function:: int dir_probe(const CacheKey * key, Stripe * d, Dir * result, Dir ** last_collision)
 
   Probe the stripe directory for a candidate directory entry.
 

doc/developer-guide/cache-architecture/data-structures.en.rst

@@ -27,9 +27,9 @@ Data Structures
 
    hide empty members
 
-   CacheHostRecord *-- "*" Stripe : Vol >
+   CacheHostRecord *-- "*" Stripe : stripe >
    CacheHostRecord *-- "*" CacheVol : cp >
-   CacheVol *-- "*" Stripe : Vol >
+   CacheVol *-- "*" Stripe : stripe >
 
 .. var:: size_t STORE_BLOCK_SIZE = 8192
 
@@ -58,7 +58,7 @@ Data Structures
 
       The cache volumes that are part of this cache host record.
 
-   .. member:: Vol ** vols
+   .. member:: Stripe ** vols
 
       The stripes that are part of the cache volumes. This is the union over the stripes of
       :member:`CacheHostRecord::cp`
@@ -133,7 +133,7 @@ Data Structures
 
    * Timestamps for request and response from :term:`origin server`.
 
-.. class:: Vol
+.. class:: Stripe
 
    This represents a :term:`storage unit` inside a :term:`cache volume`.
 
@@ -272,18 +272,18 @@ Data Structures
 
       The number of volume blocks in the span.
 
-   .. member:: DiskVolBlock vol_info[1]
+   .. member:: DiskStripeBlock vol_info[1]
 
       A flexible array. The actual length of this array is :code:`num_diskvol_blks` and each element describes
       a span block.
 
-.. class:: DiskVolBlock
+.. class:: DiskStripeBlock
 
-   A description of a span stripe (Vol) block . This is a serialized data structure.
+   A description of a span stripe (Stripe) block . This is a serialized data structure.
 
    .. member:: uint64_t offset
 
-      Offset in the span of the start of the span stripe (Vol) block, in bytes.
+      Offset in the span of the start of the span stripe (Stripe) block, in bytes.
 
    .. member:: uint64_t len
 
@@ -302,7 +302,7 @@ Data Structures
       In use or free flag - set if the span block is not in use by a cache volume.
 
 
-.. class:: VolHeaderFooter
+.. class:: StripeHeaderFooter
 
    .. member:: unsigned int magic
 
@@ -350,29 +350,29 @@ Data Structures
       for a segment, in the same order as the segments in the directory.
 
 
-.. class:: DiskVolBlockQueue
+.. class:: DiskStripeBlockQueue
 
-   .. member:: DiskVolBlock* b
+   .. member:: DiskStripeBlock* b
 
    .. member:: int new_block
 
-      Indicates if this is a new stripe rather than an existing one. In case a stripe is new ATS decides to clear that stripe(:class:`Vol`)
+      Indicates if this is a new stripe rather than an existing one. In case a stripe is new ATS decides to clear that stripe(:class:`Stripe`)
 
-   .. member:: LINK<DiskVolBlockQueue> link
+   .. member:: LINK<DiskStripeBlockQueue> link
 
 
-.. class:: DiskVol
+.. class:: DiskStripe
 
    Describes the Disk that contains the stripe identified by vol_number. This class also contains the queue
-   containing all the DiskVolBlock
+   containing all the DiskStripeBlock
 
    .. member:: int num_volblocks
 
       Number of blocks in the stripe identified by vol_number
 
    .. member:: int vol_number
 
-      Identification number of the stripe (:class:`Vol`)
+      Identification number of the stripe (:class:`Stripe`)
 
    .. member:: uint64_t size
 
@@ -382,7 +382,7 @@ Data Structures
 
       The disk containing the stripe
 
-   .. member:: Queue<DiskVolBlockQueue> dpb_queue
+   .. member:: Queue<DiskStripeBlockQueue> dpb_queue
 
 .. enum:: CacheType
 
@@ -407,13 +407,13 @@ Data Structures
 
    .. member:: int num_vols
 
-      Number of stripes(:class:`Vol`) contained in this volume
+      Number of stripes(:class:`Stripe`) contained in this volume
 
-   .. member:: Vol** vols
+   .. member:: Stripe** vols
 
-      :class:`Vol` represents a single stripe in the disk. vols contains all the stripes this volume is made up of
+      :class:`Stripe` represents a single stripe in the disk. vols contains all the stripes this volume is made up of
 
-   .. member:: DiskVol** disk_vols
+   .. member:: DiskStripe** disk_vols
 
       disk_vols contain references to the disks of all the stripes in this volume
 
@@ -462,9 +462,9 @@ Data Structures
       A generic class:`CacheHostRecord` that contains all cache volumes that are not explicitly
       assigned in :file:`hosting.config`.
 
-   .. function:: Vol * key_to_vol(const char * key, const char * host, int host_len)
+   .. function:: Stripe * key_to_vol(const char * key, const char * host, int host_len)
 
-      Compute the stripe (:code:`Vol*`) for a cache :arg:`key` and :arg:`host`. The :arg:`host` is
+      Compute the stripe (:code:`Stripe *`) for a cache :arg:`key` and :arg:`host`. The :arg:`host` is
       used to find the appropriate :class:`CacheHostRecord` instance. From there the stripe
       assignment slot is determined by taking bits 64..83 (20 bits) of the cache :arg:`key` modulo
       the stripe assignment array count (:code:`VOL_HASH_TABLE_SIZE`). These bits are the third 32

include/iocore/cache/CacheVC.h

@@ -48,7 +48,7 @@
 
 #include <cstdint>
 
-struct Vol;
+struct Stripe;
 
 struct CacheVC : public CacheVConnection {
   CacheVC();
@@ -270,7 +270,7 @@ struct CacheVC : public CacheVConnection {
   uint32_t write_len;    // for communicating with agg_copy
   uint32_t agg_len;      // for communicating with aggWrite
   uint32_t write_serial; // serial of the final write for SYNC
-  Vol *vol;
+  Stripe *vol;
   Dir *last_collision;
   Event *trigger;
   CacheKey *read_key;

src/iocore/cache/CMakeLists.txt

@@ -33,7 +33,7 @@ add_library(
   RamCacheCLFUS.cc
   RamCacheLRU.cc
   Store.cc
-  Vol.cc
+  Stripe.cc
 )
 add_library(ts::inkcache ALIAS inkcache)