Add the utility function to clear page cache

cpp/include/kvikio/file_utils.hpp

@@ -180,4 +180,23 @@ std::pair<std::size_t, std::size_t> get_page_cache_info(std::string const& file_
  * @sa `get_page_cache_info(std::string const&)` overload.
  */
 std::pair<std::size_t, std::size_t> get_page_cache_info(int fd);
+
+/**
+ * @brief Clear the page cache
+ *
+ * @param reclaim_dentries_and_inodes Whether to free reclaimable slab objects which include
+ * dentries and inodes.
+ * - If `true`, equivalent to executing `echo 3 > /proc/sys/vm/drop_caches`;
+ * - If `false`, equivalent to executing `echo 1 > /proc/sys/vm/drop_caches`.
+ * @param clear_dirty_pages Whether to trigger the writeback process to clear the dirty pages. If
+ * `true`, `sync` will be called prior to cache clearing.
+ * @return Whether the page cache has been successfully cleared
+ *
+ * @note This function creates a child process and executes the cache clearing shell command with
+ * `sudo`. Superuser privilege is therefore needed for the function to return `true`.
+ *
+ * @throws kvikio::GenericSystemError if somehow the child process could not be created, or its
+ * status could not be retrieved
+ */
+bool clear_page_cache(bool reclaim_dentries_and_inodes = true, bool clear_dirty_pages = true);
 }  // namespace kvikio

cpp/src/file_utils.cpp

@@ -18,7 +18,10 @@
 #include <sys/mman.h>
 #include <sys/stat.h>
 #include <unistd.h>
+
+#include <sstream>
 #include <stdexcept>
+#include <string>
 #include <system_error>
 #include <utility>
 #include <vector>
@@ -209,4 +212,16 @@ std::pair<std::size_t, std::size_t> get_page_cache_info(int fd)
   SYSCALL_CHECK(munmap(addr, file_size));
   return {num_pages_in_page_cache, num_pages};
 }
+
+bool clear_page_cache(bool reclaim_dentries_and_inodes, bool clear_dirty_pages)
+{
+  KVIKIO_NVTX_FUNC_RANGE();
+  if (clear_dirty_pages) { sync(); }
+  std::string param = reclaim_dentries_and_inodes ? "3" : "1";
+  std::stringstream ss;
+  ss << "echo " << param << " | sudo tee /proc/sys/vm/drop_caches 1>/dev/null";
+  auto ret = system(ss.str().c_str());
+  SYSCALL_CHECK(ret);
+  return ret == 0;
+}
 }  // namespace kvikio

docs/source/api.rst

@@ -11,6 +11,10 @@ CuFile
 .. autoclass:: IOFuture
     :members:
 
+.. autofunction:: get_page_cache_info
+
+.. autofunction:: clear_page_cache
+
 CuFile driver
 -------------
 .. currentmodule:: kvikio.cufile_driver

python/kvikio/kvikio/__init__.py

@@ -14,14 +14,15 @@
 
 from kvikio._lib.defaults import CompatMode  # noqa: F401
 from kvikio._version import __git_commit__, __version__
-from kvikio.cufile import CuFile, get_page_cache_info
+from kvikio.cufile import CuFile, clear_page_cache, get_page_cache_info
 from kvikio.remote_file import RemoteFile, is_remote_file_available
 
 __all__ = [
     "__git_commit__",
     "__version__",
     "CuFile",
     "get_page_cache_info",
+    "clear_page_cache",
     "RemoteFile",
     "is_remote_file_available",
 ]

python/kvikio/kvikio/_lib/file_handle.pyx

@@ -185,6 +185,10 @@ cdef extern from "<kvikio/file_utils.hpp>" nogil:
     pair[size_t, size_t] cpp_get_page_cache_info_int \
         "kvikio::get_page_cache_info"(int fd) except +
 
+    bool cpp_clear_page_cache "kvikio::clear_page_cache" \
+        (bool reclaim_dentries_and_inodes, bool clear_dirty_pages) \
+        except +
+
 
 def get_page_cache_info(file: Union[os.PathLike, str, int, io.IOBase]) \
         -> tuple[int, int]:
@@ -202,3 +206,7 @@ def get_page_cache_info(file: Union[os.PathLike, str, int, io.IOBase]) \
     else:
         raise ValueError("The type of `file` must be `os.PathLike`, `str`, `int`, "
                          "or `io.IOBase`")
+
+
+def clear_page_cache(reclaim_dentries_and_inodes: bool, clear_dirty_pages: bool):
+    return cpp_clear_page_cache(reclaim_dentries_and_inodes, clear_dirty_pages)

python/kvikio/kvikio/cufile.py

@@ -458,3 +458,27 @@ def get_page_cache_info(
         and the total number of pages.
     """
     return file_handle.get_page_cache_info(file)
+
+
+def clear_page_cache(
+    reclaim_dentries_and_inodes: bool = True, clear_dirty_pages: bool = True
+) -> bool:
+    """Clear the page cache
+
+    Parameters
+    ----------
+    reclaim_dentries_and_inodes: bool, optional
+        Whether to free reclaimable slab objects which include dentries and inodes.
+
+        - If `true`, equivalent to executing `echo 3 > /proc/sys/vm/drop_caches`;
+        - If `false`, equivalent to executing `echo 1 > /proc/sys/vm/drop_caches`.
+    clear_dirty_pages: bool, optional
+        Whether to trigger the writeback process to clear the dirty pages. If `true`,
+        `sync` will be called prior to cache dropping.
+
+    Returns
+    -------
+    bool
+        Whether the page cache has been successfully cleared.
+    """
+    return file_handle.clear_page_cache(reclaim_dentries_and_inodes, clear_dirty_pages)