Add example of openat() on Windows for WG21 paper.

Author: ned14

cmake/tests.cmake

@@ -49,6 +49,7 @@ set(llfio_COMPILE_TESTS
   "example/malloc2.cpp"
   "example/map_file.cpp"
   "example/mapped_file.cpp"
+  "example/path_view_openat.cpp"
   "example/read_directory.cpp"
   "example/read_entire_file1.cpp"
   "example/read_stats.cpp"

doc/html

@@ -0,0 +1,128 @@
+/* Examples of LLFIO use
+(C) 2024 Niall Douglas <http://www.nedproductions.biz/> (2 commits)
+File Created: Aug 2024
+
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License in the accompanying file
+Licence.txt or at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file Licence.txt or copy at
+          http://www.boost.org/LICENSE_1_0.txt)
+*/
+
+#include "../include/llfio.hpp"
+
+#if defined(_WIN32) && _HAS_CXX20
+#include "../include/llfio/v2.0/detail/impl/windows/import.hpp"
+
+#include <variant>
+
+using namespace LLFIO_V2_NAMESPACE;
+using namespace LLFIO_V2_NAMESPACE::windows_nt_kernel;
+using namespace std;
+
+HANDLE openat(HANDLE base, path_view path)
+{
+  static constexpr DWORD access = GENERIC_READ;
+  static constexpr DWORD share =
+  FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE;
+  static constexpr DWORD creation = OPEN_EXISTING;
+  static constexpr DWORD flags = FILE_ATTRIBUTE_NORMAL;
+  return visit(
+  [&](auto sv) -> HANDLE
+  {
+    using type = typename decltype(sv)::value_type;
+    if constexpr(is_same_v<type, byte>)
+    {
+      if(sv.size() == 16)
+      {
+        FILE_ID_DESCRIPTOR fid{};
+        fid.dwSize = sizeof(fid);
+        fid.Type = 1;
+        memcpy(&fid.ObjectId, sv.data(), 16);
+        return OpenFileById(base, &fid, access, share, nullptr, flags);
+      }
+      throw std::runtime_error("binary key must be exactly 16 bytes long");
+    }
+    // A "\!!\" or "\??\" prefix enables direct use of the NT kernel API
+    // or setting base, as the Win32 doesn't support paths relative to a base
+    const bool is_ntpath =
+    sv.size() >= 4 && sv[0] == '\\' && sv[3] == '\\' &&
+    ((sv[1] == '!' && sv[2] == '!') || (sv[1] == '?' && sv[2] == '?'));
+    if(base != nullptr || is_ntpath)
+    {
+      // The NT kernel always takes the system wide encoding
+      auto zpath = path.render_unterminated<wchar_t>(path);
+      UNICODE_STRING _path{};
+      _path.Buffer = const_cast<wchar_t *>(zpath.data());
+      _path.MaximumLength =
+      (_path.Length = static_cast<USHORT>(zpath.size() * sizeof(wchar_t))) +
+      sizeof(wchar_t);
+      // The "\!!\" prefix is library local and the NT kernel doesn't
+      // understand it, so strip it off
+      if(zpath.size() >= 4 && _path.Buffer[0] == '\\' &&
+         _path.Buffer[1] == '!' && _path.Buffer[2] == '!' &&
+         _path.Buffer[3] == '\\')
+      {
+        _path.Buffer += 3;
+        _path.Length -= 3 * sizeof(wchar_t);
+        _path.MaximumLength -= 3 * sizeof(wchar_t);
+      }
+
+      OBJECT_ATTRIBUTES oa{};
+      oa.Length = sizeof(OBJECT_ATTRIBUTES);
+      oa.ObjectName = &_path;
+      oa.RootDirectory = base;
+      oa.Attributes = 0;
+
+      IO_STATUS_BLOCK isb{};
+      LARGE_INTEGER AllocationSize{};
+      HANDLE ret = INVALID_HANDLE_VALUE;
+      NTSTATUS ntstat =
+      NtCreateFile(&ret, access, &oa, &isb, &AllocationSize, 0, share,
+                   FILE_OPEN, FILE_SYNCHRONOUS_IO_NONALERT, nullptr, 0);
+      if(ntstat < 0)
+      {
+        // Might want to call RtlNtStatusToDosError(ntstat)?
+      }
+      return ret;
+    }
+    else
+    {
+      if constexpr(is_same_v<type, char>)
+      {
+        // Render to the system narrow encoding null terminated
+        auto zpath = path.render_null_terminated<char>(path);
+        return CreateFileA(zpath.c_str(), access, share, nullptr, creation,
+                           flags, nullptr);
+      }
+      // Render to the system wide encoding null terminated
+      auto zpath = path.render_null_terminated<wchar_t>(path);
+      return CreateFileW(zpath.c_str(), access, share, nullptr, creation,
+                         flags, nullptr);
+    }
+    // Should never reach here
+    std::terminate();
+  },
+  path);
+}
+#endif
+
+// clang-format off
+
+int main()
+{
+  return 0;
+}

example/path_view_openat.cpp

@@ -1,4 +1,4 @@
 // Note the second line of this file must ALWAYS be the git SHA, third line ALWAYS the git SHA update time
-#define LLFIO_PREVIOUS_COMMIT_REF    c0326169a2f9577d617f38dd039df21f7492a548
-#define LLFIO_PREVIOUS_COMMIT_DATE   "2024-08-18 12:32:44 +00:00"
-#define LLFIO_PREVIOUS_COMMIT_UNIQUE c0326169
+#define LLFIO_PREVIOUS_COMMIT_REF    dfe95ff5e36c495df11f9a4420ddeb866be4d658
+#define LLFIO_PREVIOUS_COMMIT_DATE   "2024-08-20 07:56:43 +00:00"
+#define LLFIO_PREVIOUS_COMMIT_UNIQUE dfe95ff5

include/llfio/revision.hpp

@@ -85,6 +85,8 @@ namespace ip
   /*! \class address
   \brief A version independent IP address.
 
+  \warning This is deprecated and scheduled for removal in 2025.
+
   This is inspired by `asio::ip::address`, but it also adds `port()` from `asio::ip::endpoint`
   and a few other observer member functions i.e. it fuses ASIO's many types into one.
 
@@ -238,6 +240,8 @@ namespace ip
   /*! \brief Retrieve a list of potential `address` for a given name and service e.g.
   "www.google.com" and "https" optionally within a bounded deadline.
 
+  \warning This is deprecated and scheduled for removal in 2025.
+
   The object returned by this function can take many seconds to become ready as multiple network requests may
   need to be made. The deadline can be used to bound execution times -- like in a few
   other places in LLFIO, this deadline does not cause timed out errors, rather it aborts
@@ -354,6 +358,8 @@ namespace ip
 /*! \class byte_socket_handle
 \brief A handle to a byte-orientated socket-like entity.
 
+\warning This is deprecated and scheduled for removal in 2025.
+
 This handle, or subclasses thereof, may refer to:
 
 - a BSD socket in the kernel configured for TCP.

include/llfio/v2.0/byte_socket_handle.hpp

@@ -56,6 +56,8 @@ namespace detail
 /*! \class dynamic_thread_pool_group
 \brief Work group within the global dynamic thread pool.
 
+\warning This is deprecated and scheduled for removal in 2025.
+
 Some operating systems provide a per-process global kernel thread pool capable of
 dynamically adjusting its kernel thread count to how many of the threads in
 the pool are currently blocked. The platform will choose the exact strategy used,

include/llfio/v2.0/dynamic_thread_pool_group.hpp

@@ -1568,7 +1568,7 @@ class LLFIO_DECL path_view_component
   LLFIO_TREQUIRES(LLFIO_TPRED(is_source_acceptable<T>),
                   LLFIO_TEXPR(std::is_constructible<rendered_path<zero_termination::zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size>,
                                                     path_view_component, Args...>::value))
-  rendered_path<zero_termination::zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size> render_zero_terminated(path_view_component view,
+  rendered_path<zero_termination::zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size> render_null_terminated(path_view_component view,
                                                                                                                         Args &&...args) const
   {
     return rendered_path<zero_termination::zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size>(view, std::forward<Args>(args)...);
@@ -1579,8 +1579,8 @@ class LLFIO_DECL path_view_component
   LLFIO_TREQUIRES(LLFIO_TPRED(is_source_acceptable<T>),
                   LLFIO_TEXPR(std::is_constructible<rendered_path<zero_termination::zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size>,
                                                     path_view_component, Args...>::value))
-  rendered_path<zero_termination::not_zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size> render_not_zero_terminated(path_view_component view,
-                                                                                                                                Args &&...args) const
+  rendered_path<zero_termination::not_zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size> render_unterminated(path_view_component view,
+                                                                                                                         Args &&...args) const
   {
     return rendered_path<zero_termination::not_zero_terminated, T, AllocatorOrDeleter, _internal_buffer_size>(view, std::forward<Args>(args)...);
   }

include/llfio/v2.0/path_view.hpp

@@ -65,6 +65,8 @@ QUICKCPPLIB_BITFIELD_BEGIN(tls_algorithm)  //
 /*! \class tls_socket_handle
 \brief A handle to a TLS secure socket-like entity.
 
+\warning This is deprecated and scheduled for removal in 2025.
+
 As you cannot create one of these on your own, one generally acquires one of these
 from a `tls_socket_source`.
 */
@@ -328,6 +330,8 @@ struct tls_socket_source_implementation_information;
 \brief A source of `tls_socket_handle` and `listening_tls_socket_handle` and possibly a `byte_io_multiplexer`
 to multiplex i/o on multiple socket instances at the same time.
 
+\warning This is deprecated and scheduled for removal in 2025.
+
 The socket handles returned by this source may be _very_ different implementations
 to the kernel socket handles returned by `byte_socket_handle::byte_socket()` -- they
 may have all virtual functions overridden AND a custom i/o multiplexer set, plus RTTI
@@ -470,6 +474,8 @@ inline std::ostream &operator<<(std::ostream &s, const tls_socket_source_impleme
 /*! \class tls_socket_source_registry
 \brief A process-wide registry of `tls_socket_source`.
 
+\warning This is deprecated and scheduled for removal in 2025.
+
 Probably the most common use case for this will be fetching the default source of TLS
 secured sockets, so here is some example boilerplate:
 

include/llfio/v2.0/tls_socket_handle.hpp

@@ -1,5 +1,5 @@
 /* Integration test kernel for whether path views work
-(C) 2017-2020 Niall Douglas <http://www.nedproductions.biz/> (2 commits)
+(C) 2017-2024 Niall Douglas <http://www.nedproductions.biz/> (2 commits)
 File Created: Aug 2017
 
 
@@ -227,14 +227,16 @@ static inline void TestPathView()
   CheckPathIteration("boostish/testdir/");
   CheckPathIteration("/a/c");
   CheckPathIteration("/a/c/");
+#ifdef _WIN32
   CheckPathIteration("//a/c");
   CheckPathIteration("//a");
   CheckPathIteration("//a/");
   // CheckPathIteration("///a/c");  // FIXME: fails, /// not ///a should be iterated
   // CheckPathIteration("////a/c");  // FIXME: fails, //// not ////a should be iterated
   CheckPathIteration("//a/c//");
-  // CheckPathIteration("///a/c//");  // FIXME: fails, /// not ///a should be iterated
-  // CheckPathIteration("////a/c////");  // FIXME: fails, //// not ////a should be iterated
+// CheckPathIteration("///a/c//");  // FIXME: fails, /// not ///a should be iterated
+// CheckPathIteration("////a/c////");  // FIXME: fails, //// not ////a should be iterated
+#endif
   CheckPathIteration("/a/c//");
   CheckPathIteration("/a/c////");
   CheckPathIteration("a/c");