path_discovery: Document how path_discovery works as I keep forgetting, and greatly improve the ability to customise its operation at runtime.

4 files changed, 142 insertions, 50 deletions

diff --git a/include/llfio/v2.0/detail/impl/path_discovery.ipp b/include/llfio/v2.0/detail/impl/path_discovery.ipp
index f9d1e731..3efdcea0 100644
--- a/include/llfio/v2.0/detail/impl/path_discovery.ipp
+++ b/include/llfio/v2.0/detail/impl/path_discovery.ipp
@@ -37,36 +37,40 @@ LLFIO_V2_NAMESPACE_EXPORT_BEGIN
 
 namespace path_discovery
 {
-  struct _store
+  namespace detail
   {
-    std::mutex lock;
-    std::vector<discovered_path> all;
-    span<discovered_path> verified;
-    struct _discovered_path
+    struct _store
     {
-      filesystem::path path;
-      size_t priority{0};
-      std::string fstypename;
-      directory_handle h;  // not retained after verification
-      explicit _discovered_path(filesystem::path _path)
-          : path(std::move(_path))
+      std::mutex lock;
+      std::vector<discovered_path> all;
+      span<discovered_path> verified;
+      struct _discovered_path
       {
-      }
+        filesystem::path path;
+        size_t priority{0};
+        std::string fstypename;
+        directory_handle h;  // not retained after verification
+        explicit _discovered_path(filesystem::path _path)
+            : path(std::move(_path))
+        {
+        }
+      };
+      std::vector<_discovered_path> _all;
+      directory_handle storage_backed, memory_backed;
     };
-    std::vector<_discovered_path> _all;
-    directory_handle storage_backed, memory_backed;
-  };
-  inline _store &path_store()
-  {
-    static _store s;
-    return s;
-  }
+    inline _store &path_store()
+    {
+      static _store s;
+      return s;
+    }
+  }  // namespace detail
 
-  inline std::vector<std::pair<discovered_path::source_type, _store::_discovered_path>> _all_temporary_directories();
+  inline std::vector<std::pair<discovered_path::source_type, detail::_store::_discovered_path>> _all_temporary_directories(span<path_view> overrides,
+                                                                                                                           span<path_view> fallbacks);
 
-  span<discovered_path> all_temporary_directories(bool refresh) noexcept
+  span<discovered_path> all_temporary_directories(bool refresh, span<path_view> fallbacks, span<path_view> overrides) noexcept
   {
-    auto &ps = path_store();
+    auto &ps = detail::path_store();
     if(!refresh && !ps.all.empty())
     {
       return ps.all;
@@ -86,7 +90,7 @@ namespace path_discovery
     }
     try
     {
-      std::vector<std::pair<discovered_path::source_type, _store::_discovered_path>> raw = _all_temporary_directories();
+      std::vector<std::pair<discovered_path::source_type, detail::_store::_discovered_path>> raw = _all_temporary_directories(overrides, fallbacks);
       if(raw.empty())
       {
         LLFIO_LOG_FATAL(nullptr, "path_discovery::all_temporary_directories() sees no possible temporary directories, something has gone very wrong");
@@ -128,9 +132,9 @@ namespace path_discovery
     return ps.all;
   }
 
-  span<discovered_path> verified_temporary_directories() noexcept
+  span<discovered_path> verified_temporary_directories(const char *_storage_backed_regex, const char *_memory_backed_regex) noexcept
   {
-    auto &ps = path_store();
+    auto &ps = detail::path_store();
     if(!ps.verified.empty())
     {
       return ps.verified;
@@ -214,7 +218,7 @@ namespace path_discovery
         }
       }
       // Now partition into those with valid stat directories and those without
-      std::stable_partition(ps._all.begin(), ps._all.end(), [](const _store::_discovered_path &a) { return a.h.is_valid(); });
+      std::stable_partition(ps._all.begin(), ps._all.end(), [](const detail::_store::_discovered_path &a) { return a.h.is_valid(); });
       auto it = std::stable_partition(ps.all.begin(), ps.all.end(), [](const discovered_path &a) { return a.stat; });
       ps.verified = span<discovered_path>(ps.all.data(), it - ps.all.begin());
       if(ps.verified.empty())
@@ -231,16 +235,15 @@ namespace path_discovery
       }
 
       // Finally, need to choose storage and memory backed directories
-      std::regex storage_backed_regex("btrfs|cifs|exfat|ext[2-4]|f2fs|hfs|apfs|jfs|lxfs|nfs|nilf2|ufs|vfat|xfs|zfs|msdosfs|newnfs|ntfs|smbfs|unionfs|fat|fat32",
-                                      std::regex::icase);
-      std::regex memory_backed_regex("tmpfs|ramfs", std::regex::icase);
+      std::regex storage_backed_regex_(_storage_backed_regex, std::regex::icase);
+      std::regex memory_backed_regex_(_memory_backed_regex, std::regex::icase);
       for(size_t n = 0; n < ps.verified.size(); n++)
       {
-        if(!ps.storage_backed.is_valid() && std::regex_match(ps._all[n].fstypename, storage_backed_regex))
+        if(!ps.storage_backed.is_valid() && std::regex_match(ps._all[n].fstypename, storage_backed_regex_))
         {
           ps.storage_backed = std::move(ps._all[n].h);
         }
-        if(!ps.memory_backed.is_valid() && std::regex_match(ps._all[n].fstypename, memory_backed_regex))
+        if(!ps.memory_backed.is_valid() && std::regex_match(ps._all[n].fstypename, memory_backed_regex_))
         {
           ps.memory_backed = std::move(ps._all[n].h);
         }
@@ -266,13 +269,13 @@ namespace path_discovery
   const path_handle &storage_backed_temporary_files_directory() noexcept
   {
     (void) verified_temporary_directories();
-    auto &ps = path_store();
+    auto &ps = detail::path_store();
     return ps.storage_backed;
   }
   const path_handle &memory_backed_temporary_files_directory() noexcept
   {
     (void) verified_temporary_directories();
-    auto &ps = path_store();
+    auto &ps = detail::path_store();
     return ps.memory_backed;
   }
 }  // namespace path_discovery
diff --git a/include/llfio/v2.0/detail/impl/posix/path_discovery.ipp b/include/llfio/v2.0/detail/impl/posix/path_discovery.ipp
index c7825d9e..98b0ec92 100644
--- a/include/llfio/v2.0/detail/impl/posix/path_discovery.ipp
+++ b/include/llfio/v2.0/detail/impl/posix/path_discovery.ipp
@@ -34,11 +34,20 @@ LLFIO_V2_NAMESPACE_EXPORT_BEGIN
 
 namespace path_discovery
 {
-  std::vector<std::pair<discovered_path::source_type, _store::_discovered_path>> _all_temporary_directories()
+  std::vector<std::pair<discovered_path::source_type, detail::_store::_discovered_path>> _all_temporary_directories(span<path_view> overrides,
+                                                                                                                    span<path_view> fallbacks)
   {
-    std::vector<std::pair<discovered_path::source_type, _store::_discovered_path>> ret;
+    std::vector<std::pair<discovered_path::source_type, detail::_store::_discovered_path>> ret;
     filesystem::path::string_type buffer;
     buffer.resize(PATH_MAX);
+    if(!overrides.empty())
+    {
+      ret.reserve(overrides.size());
+      for(auto &i : overrides)
+      {
+        ret.emplace_back(discovered_path::source_type::local, i.path());
+      }
+    }
     // Only observe environment variables if not a SUID or SGID situation
     // FIXME? Is this actually enough? What about the non-standard saved uid/gid?
     // Should I be checking if my executable is SUGID and its owning user is not mine?
@@ -130,6 +139,14 @@ namespace path_discovery
       }
     }
 
+    if(!fallbacks.empty())
+    {
+      for(auto &i : fallbacks)
+      {
+        ret.emplace_back(discovered_path::source_type::local, i.path());
+      }
+    }
+
     // If everything earlier failed e.g. if our environment block is zeroed,
     // fall back to /tmp and then /var/tmp, the last of which should succeed even if tmpfs is not mounted
     ret.emplace_back(discovered_path::source_type::hardcoded, "/tmp");
@@ -143,7 +160,10 @@ namespace path_discovery
     return ret;
   }
 
-  const path_handle &temporary_named_pipes_directory() noexcept { return storage_backed_temporary_files_directory(); }
+  const path_handle &temporary_named_pipes_directory() noexcept
+  {
+    return storage_backed_temporary_files_directory();
+  }
 }  // namespace path_discovery
 
 LLFIO_V2_NAMESPACE_END
diff --git a/include/llfio/v2.0/detail/impl/windows/path_discovery.ipp b/include/llfio/v2.0/detail/impl/windows/path_discovery.ipp
index 8411e1ee..22ec8a01 100644
--- a/include/llfio/v2.0/detail/impl/windows/path_discovery.ipp
+++ b/include/llfio/v2.0/detail/impl/windows/path_discovery.ipp
@@ -34,11 +34,20 @@ LLFIO_V2_NAMESPACE_EXPORT_BEGIN
 
 namespace path_discovery
 {
-  std::vector<std::pair<discovered_path::source_type, _store::_discovered_path>> _all_temporary_directories()
+  std::vector<std::pair<discovered_path::source_type, detail::_store::_discovered_path>> _all_temporary_directories(span<path_view> overrides,
+                                                                                                                    span<path_view> fallbacks)
   {
-    std::vector<std::pair<discovered_path::source_type, _store::_discovered_path>> ret;
+    std::vector<std::pair<discovered_path::source_type, detail::_store::_discovered_path>> ret;
     filesystem::path::string_type buffer;
     buffer.resize(32768);
+    if(!overrides.empty())
+    {
+      ret.reserve(overrides.size());
+      for(auto &i : overrides)
+      {
+        ret.emplace_back(discovered_path::source_type::local, i.path());
+      }
+    }
     // Only observe environment variables if not a SUID or SGID situation
     if(!running_under_suid_gid())
     {
@@ -98,6 +107,14 @@ namespace path_discovery
       }
     }
 
+    if(!fallbacks.empty())
+    {
+      for(auto &i : fallbacks)
+      {
+        ret.emplace_back(discovered_path::source_type::local, i.path());
+      }
+    }
+
     // Finally if everything earlier failed e.g. if our environment block is zeroed,
     // fall back to Win3.1 era "the Windows directory" which definitely won't be
     // C:\Windows nowadays
@@ -129,7 +146,7 @@ namespace path_discovery
     {
       return pipesdir;
     }
-    auto &ps = path_store();
+    auto &ps = detail::path_store();
     std::lock_guard<std::mutex> g(ps.lock);
     auto r = path_handle::path(L"\\!!\\Device\\NamedPipe\\");
     if(!r)
diff --git a/include/llfio/v2.0/path_discovery.hpp b/include/llfio/v2.0/path_discovery.hpp
index 46ce7ea1..83439465 100644
--- a/include/llfio/v2.0/path_discovery.hpp
+++ b/include/llfio/v2.0/path_discovery.hpp
@@ -35,6 +35,12 @@ LLFIO_V2_NAMESPACE_EXPORT_BEGIN
 //! \brief Contains functions used to discover suitable paths for things
 namespace path_discovery
 {
+  namespace detail
+  {
+    struct _store;
+    LLFIO_HEADERS_ONLY_FUNC_SPEC inline _store &path_store();
+  }  // namespace detail
+
   //! \brief A discovered path.
   struct discovered_path
   {
@@ -66,21 +72,70 @@ namespace path_discovery
   }
 
   /*! \brief Returns a list of potential directories which might be usuable for temporary files.
+  \param refresh Recalculate the list and all dependent lists, which are statically cached after first call.
+  \param fallbacks Additional local paths to place after the `discovered_path::source_type::system` paths,
+  which therefore would take preference over later `discovered_path::source_type::hardcoded` paths.
+  \param overrides Additional paths to place at the beginning of the list, which therefore would take
+  preference over all other paths.
 
   This is a fairly lightweight call which builds a master list of all potential temporary file directories
   given the environment block of this process (unless SUID or SGID or Privilege Elevation are in effect) and the user
   running this process. It does not verify if any of them exist, or are writable, or anything else about them.
   An internal mutex is held for the duration of this call.
 
+  Potential temporary file directories are sourced as follows:
+
+  - POSIX:
+
+      As per Unix guidelines, in order:
+
+       1. If not SUID nor SUIG situation, from these environment variables in this order of preference:
+       `"TMPDIR", "TMP", "TEMP", "TEMPDIR", "XDG_RUNTIME_DIR", "XDG_CACHE_HOME"` and `${HOME}/.cache`.
+
+       2. The `.cache` directory within the effective user's home directory (created if it doesn't exist).
+
+       3. `/tmp`.
+
+       4. `/var/tmp`.
+
+       5. `/run/user/<effective user id>`.
+
+       6. `/run/shm`.
+
+       7. `/`.
+
+  - Microsoft Windows:
+
+      1. If not SUID nor SUIG situation, from these environment variables in this order of preference:
+      `"TMP", "TEMP", "LOCALAPPDATA", "USERPROFILE"`.
+
+      2. Whatever the Shell says are the paths for: `${FOLDERID_LocalAppData}\Temp`,
+      `${FOLDERID_Profile}\AppData\Local\Temp`, `${FOLDERID_Profile}\Local Settings\Temp`.
+
+      3. `${GetWindowsDirectoryW()}\Temp`.
+
+      4. `GetSystemWindowsDirectoryW()\..\Temp`.
+
   \mallocs Allocates the master list of discovered temporary directories exactly once per process,
   unless `refresh` is true in which case the list will be refreshed. The system calls to retrieve paths
   may allocate additional memory for paths returned.
   \errors This call never fails, except to return an empty span.
   */
-  LLFIO_HEADERS_ONLY_FUNC_SPEC span<discovered_path> all_temporary_directories(bool refresh = false) noexcept;
+  LLFIO_HEADERS_ONLY_FUNC_SPEC span<discovered_path> all_temporary_directories(bool refresh = false, span<path_view> fallbacks = {},
+                                                                               span<path_view> overrides = {}) noexcept;
+
+  //! \brief The default regex used to determine what temporary directories are backed by storage not memory.
+  static constexpr const char storage_backed_regex[] =
+  "btrfs|cifs|exfat|ext[2-4]|f2fs|hfs|apfs|jfs|lxfs|nfs|nilf2|ufs|vfat|xfs|zfs|msdosfs|newnfs|ntfs|smbfs|unionfs|fat|fat32|overlayfs";
+  //! \brief The default regex used to determine what temporary directories are backed by memory not storage.
+  static constexpr const char memory_backed_regex[] = "tmpfs|ramfs";
 
   /*! \brief Returns a subset of `all_temporary_directories()` each of which has been tested to be writable
   by the current process. No testing is done of available writable space.
+  \param _storage_backed_regex The regex to use to determine which of the temporary directories are backed by
+  storage not memory. The regex is executed case insensitively.
+  \param _memory_backed_regex The regex to use to determine which of the temporary directories are backed by
+  memory not storage. The regex is executed case insensitively.
 
   After this call returns, the successfully probed entries returned by `all_temporary_directories()` will have their
   stat structure set. As the probing involves creating a non-zero sized file in each possible temporary
@@ -91,15 +146,14 @@ namespace path_discovery
   \errors This call never fails, though if it fails to find any writable temporary directory, it will
   terminate the process.
   */
-  LLFIO_HEADERS_ONLY_FUNC_SPEC span<discovered_path> verified_temporary_directories() noexcept;
+  LLFIO_HEADERS_ONLY_FUNC_SPEC span<discovered_path> verified_temporary_directories(const char *_storage_backed_regex = storage_backed_regex,
+                                                                                    const char *_memory_backed_regex = memory_backed_regex) noexcept;
 
   /*! \brief Returns a reference to an open handle to a verified temporary directory where files created are
   stored in a filesystem directory, usually under the current user's quota.
 
-  This is implemented by iterating all of the paths returned by `verified_temporary_directories()`
-  and checking what file system is in use. The following regex is used:
-
-  `btrfs|cifs|exfat|ext(2|3|4)|f2fs|hfs|apfs|jfs|lxfs|nfs|nilf2|ufs|vfat|xfs|zfs|msdosfs|newnfs|ntfs|smbfs|unionfs|fat|fat32`
+  This is implemented by `verified_temporary_directories()` iterating all of the paths returned by
+  and checking what file system is in use, comparing it to `storage_backed_regex`.
 
   The handle is created during `verified_temporary_directories()` and is statically cached thereafter.
   */
@@ -109,10 +163,8 @@ namespace path_discovery
   stored in memory/paging file, and thus access may be a lot quicker, but stronger limits on
   capacity may apply.
 
-  This is implemented by iterating all of the paths returned by `verified_temporary_directories()`
-  and checking what file system is in use. The following regex is used:
-
-  `tmpfs|ramfs`
+  This is implemented by `verified_temporary_directories()` iterating all of the paths returned by
+  and checking what file system is in use, comparing it to `memory_backed_regex`.
 
   The handle is created during `verified_temporary_directories()` and is statically cached thereafter.