more comments for new_caller_controlled_max_limit

Signed-off-by: Alex Chi Z <chi@neon.tech>

pageserver/src/tenant/storage_layer/image_layer.rs

@@ -995,7 +995,7 @@ impl<'a, 'ctx> ImageLayerIterator<'a, 'ctx> {
         // We want to have exactly one read syscall (plus several others for index lookup) for each `next_batch` call.
         // Therefore, we enforce `self.max_read_size` by ourselves instead of using the VectoredReadPlanner's capability,
         // to avoid splitting into two I/Os.
-        let mut read_planner = VectoredReadPlanner::new_without_max_limit();
+        let mut read_planner = VectoredReadPlanner::new_caller_controlled_max_limit();
         let mut cnt = 0;
         let mut start_pos = None;
         let mut range_end_handled = false;

pageserver/src/tenant/vectored_blob_io.rs

@@ -175,7 +175,12 @@ impl VectoredReadPlanner {
         }
     }
 
-    pub fn new_without_max_limit() -> Self {
+    /// This function should *only* be used if the caller has a way to control the limit. e.g., in `ImageLayerIterator`,
+    /// it uses the vectored read planner to avoid duplicated logic on handling blob start/end, while expecting the vectored
+    /// read planner to give a single read to a continuous range of bytes in the image layer. Therefore, it does not need the
+    /// code path to split reads into chunks of `max_read_size`, and controls the read size itself.
+    #[cfg(test)]
+    pub(crate) fn new_caller_controlled_max_limit() -> Self {
         Self {
             blobs: BTreeMap::new(),
             prev: None,