First cut at new volume configs for RAM cache

Author: zwoop

configs/volume.config.default

@@ -29,6 +29,37 @@
 #  disk (assuming each disk has enough free space available).
 #
 # To create one volume of size 10% of the total cache space and
-# another 1 Gig  volume,
+# another 1 Gig volume,
 #  volume=1 scheme=http size=10%
 #  volume=2 scheme=http size=1024
+#
+# Additional optional parameters:
+#
+#  ramcache=true/false
+#    Enable or disable RAM cache for this volume (default: true)
+#
+#  ram_cache_size=<size>
+#    Allocate a dedicated RAM cache pool for this volume (e.g., 512M, 2G)
+#    This amount is automatically subtracted from the global ram_cache.size
+#    setting, with the remainder shared among other volumes.
+#
+#  ram_cache_cutoff=<size>
+#    Override the global ram_cache_cutoff for this volume (e.g., 64K, 1M)
+#    Objects larger than this will not be stored in RAM cache.
+#
+#  avg_obj_size=<size>
+#    Override the global min_average_object_size for this volume
+#
+#  fragment_size=<size>
+#    Override the global target_fragment_size for this volume (max: 4MB)
+#
+# Advanced RAM cache configuration examples:
+#
+# Example 1: Volume with dedicated 2GB RAM cache
+#  volume=1 scheme=http size=40% ram_cache_size=2G
+#
+# Example 2: Small objects with custom cutoff and dedicated RAM
+#  volume=2 scheme=http size=20% ram_cache_size=512M ram_cache_cutoff=64K
+#
+# Example 3: Large media with higher cutoff (shares remaining RAM pool)
+#  volume=3 scheme=http size=40% ram_cache_cutoff=1M

doc/admin-guide/files/volume.config.en.rst

@@ -73,21 +73,66 @@ Optional directory entry sizing
 
 You can also add an option ``avg_obj_size=<size>`` to the volume configuration
 line. This overrides the global :ts:cv:`proxy.config.cache.min_average_object_size`
-configuration for this volume. This is useful if you have a volume that is dedicated
-for say very small objects, and you need a lot of directory entries to store them.
+configuration for this volume. The size supports multipliers (K, M, G, T) for
+convenience (e.g., ``avg_obj_size=64K`` or ``avg_obj_size=1M``). This is useful
+if you have a volume that is dedicated for say very small objects, and you need
+a lot of directory entries to store them.
 
 Optional fragment size setting
 ------------------------------
 
 You can also add an option ``fragment_size=<size>`` to the volume configuration
 line. This overrides the global :ts:cv:`proxy.config.cache.target_fragment_size`
-configuration for this volume. This allows for a smaller, or larger, fragment size
-for a particular volume. This may be useful together with ``avg_obj_size`` as well,
-since a larger fragment size could reduce the number of directory entries needed
-for a large object.
+configuration for this volume. The size supports multipliers (K, M, G, T) for
+convenience (e.g., ``fragment_size=512K`` or ``fragment_size=2M``). This allows
+for a smaller, or larger, fragment size for a particular volume. This may be
+useful together with ``avg_obj_size`` as well, since a larger fragment size could
+reduce the number of directory entries needed for a large object.
 
 Note that this setting has a maximmum value of 4MB.
 
+Optional RAM cache size allocation
+-----------------------------------
+
+You can add an option ``ram_cache_size=<size>`` to the volume configuration line
+to allocate a dedicated RAM cache pool for this volume. The size supports
+multipliers (K, M, G, T) for convenience (e.g., ``ram_cache_size=512M`` or
+``ram_cache_size=2G``). Setting ``ram_cache_size=0`` disables the RAM cache
+for this volume, which is equivalent to ``ramcache=false``.
+
+When ``ram_cache_size`` is specified for a volume, that amount is **automatically
+subtracted** from the global :ts:cv:`proxy.config.cache.ram_cache.size` setting,
+and the remainder is shared among volumes without private allocations. This ensures
+total RAM cache usage never exceeds the configured global limit.
+
+For example, if the global RAM cache size is 4GB and you allocate 1GB to volume 1
+and 512MB to volume 2, the remaining 2.5GB will be distributed among other volumes
+using the normal proportional allocation based on disk space.
+
+**Important notes:**
+
+* If the sum of all ``ram_cache_size`` allocations exceeds the global RAM cache size,
+  a warning is logged and the private allocations are disabled, falling back to
+  the standard shared allocation.
+* This setting only takes effect when :ts:cv:`proxy.config.cache.ram_cache.size`
+  is set to a positive value (not ``-1`` for automatic sizing).
+
+Optional RAM cache cutoff override
+-----------------------------------
+
+You can add an option ``ram_cache_cutoff=<size>`` to the volume configuration line
+to override the global :ts:cv:`proxy.config.cache.ram_cache_cutoff` setting for
+this specific volume. The size supports multipliers (K, M, G, T) for convenience
+(e.g., ``ram_cache_cutoff=64K`` or ``ram_cache_cutoff=1M``).
+
+This cutoff determines the maximum object size that will be stored in the RAM cache.
+Objects larger than this size will only be stored on disk. Setting different cutoffs
+per volume allows you to:
+
+* Use larger cutoffs for volumes serving frequently accessed large objects
+* Use smaller cutoffs for volumes with many small objects to maximize RAM cache hits
+* Disable RAM caching entirely for certain objects by setting a very low cutoff
+
 Exclusive spans and volume sizes
 ================================
 
@@ -126,5 +171,24 @@ ramcache has been disabled.::
     volume=1 scheme=http size=20%
     volume=2 scheme=http size=20%
     volume=3 scheme=http size=20%
-    volume=4 scheme=http size=20% avg_obj_size=4096
-    volume=5 scheme=http size=20% ramcache=false fragment_size=524288
+    volume=4 scheme=http size=20% avg_obj_size=4K
+    volume=5 scheme=http size=20% ramcache=false fragment_size=512K
+
+The following example shows advanced RAM cache configuration with dedicated
+allocations and custom cutoffs::
+
+    # Volume 1: General content with 2GB dedicated RAM cache
+    volume=1 scheme=http size=40% ram_cache_size=2G
+
+    # Volume 2: Small API responses with custom cutoff and 512MB RAM cache
+    volume=2 scheme=http size=20% ram_cache_size=512M ram_cache_cutoff=64K
+
+    # Volume 3: Large media with higher cutoff for thumbnails
+    volume=3 scheme=http size=40% ram_cache_cutoff=1M
+
+In this example, assuming a global ``proxy.config.cache.ram_cache.size`` of 4GB:
+
+* Volume 1 gets a dedicated 2GB RAM cache allocation
+* Volume 2 gets a dedicated 512MB RAM cache allocation and only caches objects up to 64KB
+* Volume 3 shares from the remaining 1.5GB pool (4GB - 2GB - 512MB) and caches objects up to 1MB
+* The automatic subtraction ensures total RAM usage stays within the 4GB limit

src/iocore/cache/CacheHosting.cc

@@ -652,6 +652,8 @@ ConfigVolumes::BuildListFromString(char *config_file_path, char *file_buf)
     bool        ramcache_enabled = true;
     int         avg_obj_size     = -1; // Defaults
     int         fragment_size    = -1;
+    int64_t     ram_cache_size   = -1; // -1 means use shared allocation
+    int64_t     ram_cache_cutoff = -1; // -1 means use global cutoff
 
     while (true) {
       // skip all blank spaces at beginning of line
@@ -741,16 +743,24 @@ ConfigVolumes::BuildListFromString(char *config_file_path, char *file_buf)
         }
       } else if (strcasecmp(tmp, "avg_obj_size") == 0) { // match avg_obj_size
         tmp          += 13;
-        avg_obj_size  = atoi(tmp);
+        avg_obj_size  = static_cast<int>(ink_atoi64(tmp));
 
-        while (ParseRules::is_digit(*tmp)) {
+        if (avg_obj_size < 0) {
+          err = "Invalid avg_obj_size value (must be >= 0)";
+          break;
+        }
+        while (*tmp && (ParseRules::is_digit(*tmp) || strchr("kmgtKMGT", *tmp))) {
           tmp++;
         }
       } else if (strcasecmp(tmp, "fragment_size") == 0) { // match fragment_size
         tmp           += 14;
-        fragment_size  = atoi(tmp);
+        fragment_size  = static_cast<int>(ink_atoi64(tmp));
 
-        while (ParseRules::is_digit(*tmp)) {
+        if (fragment_size < 0) {
+          err = "Invalid fragment_size value (must be >= 0)";
+          break;
+        }
+        while (*tmp && (ParseRules::is_digit(*tmp) || strchr("kmgtKMGT", *tmp))) {
           tmp++;
         }
       } else if (strcasecmp(tmp, "ramcache") == 0) { // match ramcache
@@ -765,6 +775,29 @@ ConfigVolumes::BuildListFromString(char *config_file_path, char *file_buf)
           err = "Unexpected end of line";
           break;
         }
+      } else if (strcasecmp(tmp, "ram_cache_size") == 0) { // match ram_cache_size
+        tmp            += 15;
+        ram_cache_size  = ink_atoi64(tmp);
+
+        if (ram_cache_size < 0) {
+          err = "Invalid ram_cache_size value (must be >= 0)";
+          break;
+        }
+        // Note: ram_cache_size=0 disables RAM cache for this volume, same as ramcache=false
+        while (*tmp && (ParseRules::is_digit(*tmp) || strchr("kmgtKMGT", *tmp))) {
+          tmp++;
+        }
+      } else if (strcasecmp(tmp, "ram_cache_cutoff") == 0) { // match ram_cache_cutoff
+        tmp              += 17;
+        ram_cache_cutoff  = ink_atoi64(tmp);
+
+        if (ram_cache_cutoff < 0) {
+          err = "Invalid ram_cache_cutoff value (must be >= 0)";
+          break;
+        }
+        while (*tmp && (ParseRules::is_digit(*tmp) || strchr("kmgtKMGT", *tmp))) {
+          tmp++;
+        }
       }
 
       // ends here
@@ -791,6 +824,8 @@ ConfigVolumes::BuildListFromString(char *config_file_path, char *file_buf)
       configp->size             = size;
       configp->avg_obj_size     = avg_obj_size;
       configp->fragment_size    = fragment_size;
+      configp->ram_cache_size   = ram_cache_size;
+      configp->ram_cache_cutoff = ram_cache_cutoff;
       configp->cachep           = nullptr;
       configp->ramcache_enabled = ramcache_enabled;
       cp_queue.enqueue(configp);

src/iocore/cache/CacheProcessor.cc

@@ -1170,6 +1170,8 @@ cplist_update()
           cp->ramcache_enabled = config_vol->ramcache_enabled;
           cp->avg_obj_size     = config_vol->avg_obj_size;
           cp->fragment_size    = config_vol->fragment_size;
+          cp->ram_cache_size   = config_vol->ram_cache_size;
+          cp->ram_cache_cutoff = config_vol->ram_cache_cutoff;
           config_vol->cachep   = cp;
         } else {
           /* delete this volume from all the disks */
@@ -1442,22 +1444,54 @@ CacheProcessor::cacheInitialized()
         }
       }
 
+      // Calculate total private RAM allocations from per-volume configurations
       int64_t http_ram_cache_size = 0;
+      int64_t total_private_ram   = 0;
+
+      if (cache_config_ram_cache_size != AUTO_SIZE_RAM_CACHE) {
+        CacheVol *cp = cp_list.head;
+
+        for (; cp; cp = cp->link.next) {
+          if (cp->ram_cache_size > 0) {
+            total_private_ram += cp->ram_cache_size;
+            Dbg(dbg_ctl_cache_init, "Volume %d has private RAM allocation: %" PRId64 " bytes (%" PRId64 " MB)", cp->vol_number,
+                cp->ram_cache_size, cp->ram_cache_size / (1024 * 1024));
+          }
+        }
+
+        if (total_private_ram > 0) {
+          Dbg(dbg_ctl_cache_init, "Total private RAM allocations: %" PRId64 " bytes (%" PRId64 " MB)", total_private_ram,
+              total_private_ram / (1024 * 1024));
+        }
+      }
 
-      // let us calculate the Size
       if (cache_config_ram_cache_size == AUTO_SIZE_RAM_CACHE) {
         Dbg(dbg_ctl_cache_init, "cache_config_ram_cache_size == AUTO_SIZE_RAM_CACHE");
       } else {
         // we got configured memory size
         // TODO, should we check the available system memories, or you will
         //   OOM or swapout, that is not a good situation for the server
         Dbg(dbg_ctl_cache_init, "%" PRId64 " != AUTO_SIZE_RAM_CACHE", cache_config_ram_cache_size);
-        http_ram_cache_size =
-          static_cast<int64_t>((static_cast<double>(theCache->cache_size) / total_size) * cache_config_ram_cache_size);
+
+        // Calculate shared pool: global RAM cache size minus private allocations
+        int64_t shared_pool = cache_config_ram_cache_size - total_private_ram;
+
+        if (shared_pool < 0) {
+          Warning("Total private RAM cache allocations (%" PRId64 " bytes) exceed global ram_cache.size (%" PRId64 " bytes). "
+                  "Using global limit. Consider increasing proxy.config.cache.ram_cache.size.",
+                  total_private_ram, cache_config_ram_cache_size);
+          shared_pool       = cache_config_ram_cache_size; // Fall back to using the global pool for all
+          total_private_ram = 0;                           // Disable private allocations
+        } else if (total_private_ram > 0) {
+          Dbg(dbg_ctl_cache_init, "Shared RAM cache pool (after private allocations): %" PRId64 " bytes (%" PRId64 " MB)",
+              shared_pool, shared_pool / (1024 * 1024));
+        }
+
+        http_ram_cache_size = static_cast<int64_t>((static_cast<double>(theCache->cache_size) / total_size) * shared_pool);
 
         Dbg(dbg_ctl_cache_init, "http_ram_cache_size = %" PRId64 " = %" PRId64 "Mb", http_ram_cache_size,
             http_ram_cache_size / (1024 * 1024));
-        int64_t stream_ram_cache_size = cache_config_ram_cache_size - http_ram_cache_size;
+        int64_t stream_ram_cache_size = shared_pool - http_ram_cache_size;
 
         Dbg(dbg_ctl_cache_init, "stream_ram_cache_size = %" PRId64 " = %" PRId64 "Mb", stream_ram_cache_size,
             stream_ram_cache_size / (1024 * 1024));
@@ -1470,22 +1504,49 @@ CacheProcessor::cacheInitialized()
       uint64_t total_cache_bytes     = 0; // bytes that can used in total_size
       uint64_t total_direntries      = 0; // all the direntries in the cache
       uint64_t used_direntries       = 0; //   and used
-      uint64_t total_ram_cache_bytes = 0;
+      uint64_t total_ram_cache_bytes = 0; // Total RAM cache size across all volumes
+      uint64_t shared_cache_size     = 0; // Total cache size of volumes without explicit RAM allocations
+
+      // Calculate total cache size of volumes without explicit RAM allocations
+      if (http_ram_cache_size > 0) {
+        for (int i = 0; i < gnstripes; i++) {
+          if (gstripes[i]->cache_vol->ram_cache_size <= 0) {
+            shared_cache_size += (gstripes[i]->len >> STORE_BLOCK_SHIFT);
+          }
+        }
+        Dbg(dbg_ctl_cache_init, "Shared cache size (for RAM pool distribution): %" PRId64 " blocks", shared_cache_size);
+      }
 
       for (int i = 0; i < gnstripes; i++) {
         StripeSM *stripe          = gstripes[i];
         int64_t   ram_cache_bytes = 0;
 
-        if (stripe->cache_vol->ramcache_enabled) {
-          if (http_ram_cache_size == 0) {
+        // If RAM cache enabled, check if this volume has a private RAM cache allocation
+        if (stripe->cache_vol->ramcache_enabled && stripe->cache_vol->ram_cache_size != 0) {
+          if (stripe->cache_vol->ram_cache_size > 0) {
+            int64_t volume_stripe_count = 0;
+
+            for (int j = 0; j < gnstripes; j++) {
+              if (gstripes[j]->cache_vol == stripe->cache_vol) {
+                volume_stripe_count++;
+              }
+            }
+
+            if (volume_stripe_count > 0) {
+              ram_cache_bytes = stripe->cache_vol->ram_cache_size / volume_stripe_count;
+              Dbg(dbg_ctl_cache_init, "Volume %d stripe %d using private RAM allocation: %" PRId64 " bytes (%" PRId64 " MB)",
+                  stripe->cache_vol->vol_number, i, ram_cache_bytes, ram_cache_bytes / (1024 * 1024));
+            }
+          } else if (http_ram_cache_size == 0) {
             // AUTO_SIZE_RAM_CACHE
             ram_cache_bytes = stripe->dirlen() * DEFAULT_RAM_CACHE_MULTIPLIER;
           } else {
+            // Use shared pool allocation - distribute only among volumes without explicit allocations
             ink_assert(stripe->cache != nullptr);
+            int64_t divisor = (shared_cache_size > 0) ? shared_cache_size : theCache->cache_size;
+            double  factor  = static_cast<double>(static_cast<int64_t>(stripe->len >> STORE_BLOCK_SHIFT)) / divisor;
 
-            double factor = static_cast<double>(static_cast<int64_t>(stripe->len >> STORE_BLOCK_SHIFT)) / theCache->cache_size;
-            Dbg(dbg_ctl_cache_init, "factor = %f", factor);
-
+            Dbg(dbg_ctl_cache_init, "factor = %f (divisor = %" PRId64 ")", factor, divisor);
             ram_cache_bytes = static_cast<int64_t>(http_ram_cache_size * factor);
           }
 
@@ -1497,19 +1558,19 @@ CacheProcessor::cacheInitialized()
               ram_cache_bytes, ram_cache_bytes / (1024 * 1024));
         }
 
-        uint64_t vol_total_cache_bytes  = stripe->len - stripe->dirlen();
-        total_cache_bytes              += vol_total_cache_bytes;
+        uint64_t vol_total_cache_bytes = stripe->len - stripe->dirlen();
+        uint64_t vol_total_direntries  = stripe->directory.entries();
+        uint64_t vol_used_direntries   = stripe->directory.entries_used();
+
+        total_cache_bytes += vol_total_cache_bytes;
         ts::Metrics::Gauge::increment(stripe->cache_vol->vol_rsb.bytes_total, vol_total_cache_bytes);
         ts::Metrics::Gauge::increment(stripe->cache_vol->vol_rsb.stripes);
 
         Dbg(dbg_ctl_cache_init, "total_cache_bytes = %" PRId64 " = %" PRId64 "Mb", total_cache_bytes,
             total_cache_bytes / (1024 * 1024));
 
-        uint64_t vol_total_direntries  = stripe->directory.entries();
-        total_direntries              += vol_total_direntries;
+        total_direntries += vol_total_direntries;
         ts::Metrics::Gauge::increment(stripe->cache_vol->vol_rsb.direntries_total, vol_total_direntries);
-
-        uint64_t vol_used_direntries = stripe->directory.entries_used();
         ts::Metrics::Gauge::increment(stripe->cache_vol->vol_rsb.direntries_used, vol_used_direntries);
         used_direntries += vol_used_direntries;
       }

src/iocore/cache/CacheVC.cc

@@ -412,15 +412,17 @@ CacheVC::handleReadDone(int event, Event * /* e ATS_UNUSED */)
       // Put the request in the ram cache only if its a open_read or lookup
       if (vio.op == VIO::READ && okay) {
         bool cutoff_check;
+        // Determine effective cutoff: use per-volume override if set, otherwise use global
+        int64_t effective_cutoff =
+          (stripe->cache_vol->ram_cache_cutoff > 0) ? stripe->cache_vol->ram_cache_cutoff : cache_config_ram_cache_cutoff;
         // cutoff_check :
         // doc_len == 0 for the first fragment (it is set from the vector)
         //                The decision on the first fragment is based on
         //                doc->total_len
         // After that, the decision is based of doc_len (doc_len != 0)
-        // (cache_config_ram_cache_cutoff == 0) : no cutoffs
-        cutoff_check =
-          ((!doc_len && static_cast<int64_t>(doc->total_len) < cache_config_ram_cache_cutoff) ||
-           (doc_len && static_cast<int64_t>(doc_len) < cache_config_ram_cache_cutoff) || !cache_config_ram_cache_cutoff);
+        // (effective_cutoff == 0) : no cutoffs
+        cutoff_check = ((!doc_len && static_cast<int64_t>(doc->total_len) < effective_cutoff) ||
+                        (doc_len && static_cast<int64_t>(doc_len) < effective_cutoff) || !effective_cutoff);
         if (cutoff_check && !f.doc_from_ram_cache) {
           uint64_t o = dir_offset(&dir);
           stripe->ram_cache->put(read_key, buf.get(), doc->len, http_copy_hdr, o);

src/iocore/cache/P_CacheHosting.h

@@ -298,6 +298,8 @@ struct ConfigVol {
   int       percent;
   int       avg_obj_size;
   int       fragment_size;
+  int64_t   ram_cache_size;   // Per-volume RAM cache size (-1 = use shared allocation)
+  int64_t   ram_cache_cutoff; // Per-volume RAM cache cutoff (-1 = use global cutoff)
   CacheVol *cachep;
   LINK(ConfigVol, link);
 };