feat(diskann): Add Windows DiskANN support with asynchronous I/O (#625)

Co-authored-by: ray <rui.xing@alibaba-inc.com>

Author: iaojnh

CMakeLists.txt

@@ -164,8 +164,10 @@ message(STATUS "RABITQ_SUPPORTED: ${RABITQ_SUPPORTED}")
 # DiskAnn support:
 #   - Linux x86_64 and ARM64 with io_uring, libaio, or pread
 #   - macOS ARM64 (Apple Silicon) with synchronous pread
+#   - Windows x86_64 with overlapped I/O
 if((CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "^(x86_64|amd64|AMD64|aarch64|arm64)$" AND NOT ANDROID AND NOT IOS)
-    OR (CMAKE_SYSTEM_NAME STREQUAL "Darwin" AND CMAKE_SYSTEM_PROCESSOR MATCHES "^(arm64|aarch64)$" AND NOT IOS))
+    OR (CMAKE_SYSTEM_NAME STREQUAL "Darwin" AND CMAKE_SYSTEM_PROCESSOR MATCHES "^(arm64|aarch64)$" AND NOT IOS)
+    OR (WIN32 AND CMAKE_SIZEOF_VOID_P EQUAL 8 AND CMAKE_SYSTEM_PROCESSOR MATCHES "^(x86_64|AMD64|amd64)$"))
   set(DISKANN_SUPPORTED ON)
   add_definitions(-DDISKANN_SUPPORTED=1)
 else()

python/tests/detail/fixture_helper.py

@@ -3,9 +3,13 @@
 import platform
 
 DISKANN_SUPPORTED = (
-    platform.system() == "Linux"
-    and platform.machine() in ("x86_64", "AMD64", "aarch64", "arm64")
-) or (platform.system() == "Darwin" and platform.machine() in ("aarch64", "arm64"))
+    (
+        platform.system() == "Linux"
+        and platform.machine() in ("x86_64", "AMD64", "aarch64", "arm64")
+    )
+    or (platform.system() == "Darwin" and platform.machine() in ("aarch64", "arm64"))
+    or (platform.system() == "Windows" and platform.machine() in ("x86_64", "AMD64"))
+)
 
 from typing import Any, Generator
 from zvec.typing import DataType, StatusCode, MetricType, QuantizeType
@@ -26,7 +30,8 @@ def _ensure_diskann_runtime_or_reason() -> str | None:
 
     if not DISKANN_SUPPORTED:
         _DISKANN_PRELOAD_REASON = (
-            "DiskAnn is supported on Linux (x86_64/ARM64) and macOS ARM64"
+            "DiskAnn is supported on Linux (x86_64/ARM64), macOS ARM64, "
+            "and Windows x86_64"
         )
         return _DISKANN_PRELOAD_REASON
     _DISKANN_PRELOAD_REASON = None

python/tests/test_collection_diskann.py

@@ -15,11 +15,9 @@
 
 Mirrors ``test_collection_hnsw_rabitq.py`` but targets the DiskAnn index.
 
-DiskAnn must be built for Linux (x86_64/ARM64) or macOS ARM64. Other
-platforms are skipped wholesale.
-
-If the prerequisite fails the whole module is skipped so the rest of the
-test suite is not affected. macOS uses synchronous pread.
+DiskAnn must be built for Linux (x86_64/ARM64), macOS ARM64, or Windows
+x86_64. Other platforms are skipped wholesale. Linux selects io_uring,
+libaio, or pread; macOS uses pread; Windows uses overlapped I/O.
 """
 
 from __future__ import annotations
@@ -40,8 +38,11 @@
             and platform.machine() in ("x86_64", "AMD64", "aarch64", "arm64")
         )
         or (sys.platform == "darwin" and platform.machine() in ("aarch64", "arm64"))
+        or (sys.platform == "win32" and platform.machine() in ("x86_64", "AMD64"))
+    ),
+    reason=(
+        "DiskAnn is supported on Linux (x86_64/ARM64), macOS ARM64, and Windows x86_64"
     ),
-    reason="DiskAnn is supported on Linux (x86_64/ARM64) and macOS ARM64",
 )
 
 import zvec  # noqa: E402

python/tests/test_typing.py

@@ -38,6 +38,7 @@
         (IndexType.HNSW, "HNSW"),
         (IOBackendType.PREAD, "PREAD"),
         (IOBackendType.IO_URING, "IO_URING"),
+        (IOBackendType.WINDOWS_OVERLAPPED, "WINDOWS_OVERLAPPED"),
         (MetricType.COSINE, "COSINE"),
         (QuantizeType.INT8, "INT8"),
         (StatusCode.OK, "OK"),
@@ -54,6 +55,7 @@ def test_enum_names(member, name):
         (IndexType.HNSW, 1),
         (IOBackendType.PREAD, 0),
         (IOBackendType.IO_URING, 2),
+        (IOBackendType.WINDOWS_OVERLAPPED, 3),
         (MetricType.COSINE, 3),
         (QuantizeType.INT8, 2),
         (StatusCode.OK, 0),
@@ -119,7 +121,9 @@ def test_index_type_has_member(member):
     assert member in IndexType.__members__
 
 
-@pytest.mark.parametrize("member", ["PREAD", "LIBAIO", "IO_URING"])
+@pytest.mark.parametrize(
+    "member", ["PREAD", "LIBAIO", "IO_URING", "WINDOWS_OVERLAPPED"]
+)
 def test_io_backend_type_has_member(member):
     assert member in IOBackendType.__members__
 
@@ -128,7 +132,10 @@ def test_current_io_backend_type():
     backend = zvec.io_backend_type()
     assert isinstance(backend, IOBackendType)
     assert zvec.io_backend_description()
-    if platform.system() == "Darwin":
+    if platform.system() == "Windows":
+        assert backend == IOBackendType.WINDOWS_OVERLAPPED
+        assert "overlapped" in zvec.io_backend_description().lower()
+    elif platform.system() == "Darwin":
         assert backend == IOBackendType.PREAD
         assert "pread" in zvec.io_backend_description().lower()
 

python/zvec/__init__.pyi

@@ -56,14 +56,15 @@ def io_backend_type() -> IOBackendType:
 
     Linux selects IOBackendType.IO_URING, IOBackendType.LIBAIO, or
     IOBackendType.PREAD in that order. macOS ARM64 uses IOBackendType.PREAD.
+    Windows uses IOBackendType.WINDOWS_OVERLAPPED.
     """
 
 def io_backend_description() -> str:
     """Returns a human-readable description of the current I/O backend.
 
     The description identifies io_uring, libaio, or pread. On Linux, the
     pread description includes guidance for enabling io_uring or installing
-    libaio.
+    libaio. Windows reports its overlapped-I/O backend.
     """
 
 def set_default_jieba_dict_dir(dir: str) -> None:

python/zvec/typing/__init__.pyi

@@ -132,6 +132,8 @@ class IOBackendType:
     - PREAD: Synchronous pread() — no async I/O.
     - LIBAIO: libaio loaded at runtime via dlopen().
     - IO_URING: io_uring via raw kernel syscalls (zero dependency).
+    - WINDOWS_OVERLAPPED: Windows unbuffered overlapped I/O using per-context
+      I/O completion ports.
 
     Examples:
         >>> from zvec.typing import IOBackendType
@@ -146,14 +148,19 @@ class IOBackendType:
       LIBAIO
 
       IO_URING
+
+      WINDOWS_OVERLAPPED
     """
 
-    IO_URING: typing.ClassVar[IOBackendType]  # value = <IOBackendType.IO_URING: 2>
-    LIBAIO: typing.ClassVar[IOBackendType]  # value = <IOBackendType.LIBAIO: 1>
     PREAD: typing.ClassVar[IOBackendType]  # value = <IOBackendType.PREAD: 0>
+    LIBAIO: typing.ClassVar[IOBackendType]  # value = <IOBackendType.LIBAIO: 1>
+    IO_URING: typing.ClassVar[IOBackendType]  # value = <IOBackendType.IO_URING: 2>
+    WINDOWS_OVERLAPPED: typing.ClassVar[
+        IOBackendType
+    ]  # value = <IOBackendType.WINDOWS_OVERLAPPED: 3>
     __members__: typing.ClassVar[
         dict[str, IOBackendType]
-    ]  # value = {'PREAD': <IOBackendType.PREAD: 0>, 'LIBAIO': <IOBackendType.LIBAIO: 1>, 'IO_URING': <IOBackendType.IO_URING: 2>}
+    ]  # value includes PREAD, LIBAIO, IO_URING, and WINDOWS_OVERLAPPED
 
     def __eq__(self, other: typing.Any) -> bool: ...
     def __getstate__(self) -> int: ...

src/ailego/io/io_backend_def.h

@@ -48,6 +48,8 @@ inline const char *IOBackendTypeName(IOBackendType type) {
       return "libaio";
     case IOBackendType::kPread:
       return "pread";
+    case IOBackendType::kWindowsOverlapped:
+      return "windows_overlapped";
   }
   return "unknown";
 }
@@ -71,6 +73,9 @@ inline const char *IOBackendDescription(IOBackendType type) {
 #else
       return "Synchronous pread() I/O backend.";
 #endif
+    case IOBackendType::kWindowsOverlapped:
+      return "windows_overlapped: Windows unbuffered overlapped I/O backend "
+             "using per-context I/O completion ports.";
   }
   return "Unknown I/O backend.";
 }
@@ -92,7 +97,9 @@ class IOBackend {
   IOBackendType available() {
     std::call_once(probe_once_, [this]() {
       IOBackendType selected = IOBackendType::kPread;
-#if defined(__linux) || defined(__linux__)
+#if defined(_WIN32) || defined(_WIN64)
+      selected = IOBackendType::kWindowsOverlapped;
+#elif defined(__linux) || defined(__linux__)
       if (io_uring_supported()) {
         selected = IOBackendType::kIoUring;
       } else if (LibAioLoader::Instance().load() &&

src/binding/c/c_api.cc

@@ -766,6 +766,20 @@ const char *zvec_get_default_jieba_dict_dir(void) {
 // I/O Backend Introspection
 // =============================================================================
 
+static_assert(
+    static_cast<uint32_t>(zvec::ailego::IOBackendType::kPread) ==
+    ZVEC_IO_BACKEND_TYPE_PREAD);
+static_assert(
+    static_cast<uint32_t>(zvec::ailego::IOBackendType::kLibAio) ==
+    ZVEC_IO_BACKEND_TYPE_LIBAIO);
+static_assert(
+    static_cast<uint32_t>(zvec::ailego::IOBackendType::kIoUring) ==
+    ZVEC_IO_BACKEND_TYPE_IO_URING);
+static_assert(
+    static_cast<uint32_t>(
+        zvec::ailego::IOBackendType::kWindowsOverlapped) ==
+    ZVEC_IO_BACKEND_TYPE_WINDOWS_OVERLAPPED);
+
 zvec_io_backend_type_t zvec_get_io_backend_type(void) {
   auto type = zvec::ailego::current_io_backend_type();
   return static_cast<zvec_io_backend_type_t>(static_cast<uint32_t>(type));

src/binding/python/model/common/python_config.cc

@@ -230,7 +230,8 @@ void ZVecPyConfig::Initialize(pybind11::module_ &m) {
       "as an IOBackendType enum (zvec.typing.IOBackendType). "
       "Linux selects IOBackendType.IO_URING, IOBackendType.LIBAIO, or "
       "IOBackendType.PREAD in that order. macOS ARM64 uses "
-      "IOBackendType.PREAD.");
+      "IOBackendType.PREAD. Windows uses "
+      "IOBackendType.WINDOWS_OVERLAPPED.");
 
   // Returns a human-readable description identifying io_uring, libaio, or
   // pread, with asynchronous-backend guidance for Linux pread fallback.
@@ -240,7 +241,7 @@ void ZVecPyConfig::Initialize(pybind11::module_ &m) {
       "Returns a human-readable description of the current I/O backend. "
       "The description identifies io_uring, libaio, or pread. On Linux, the "
       "pread description includes guidance for enabling io_uring or "
-      "installing libaio.");
+      "installing libaio. Windows reports its overlapped-I/O backend.");
 }
 
 

src/binding/python/typing/python_type.cc

@@ -149,6 +149,8 @@ Enumeration of supported I/O backend types for DiskAnn disk reads.
 - PREAD: Synchronous pread(); no async I/O.
 - LIBAIO: libaio loaded at runtime via dlopen().
 - IO_URING: io_uring via raw kernel syscalls (zero dependency).
+- WINDOWS_OVERLAPPED: Windows unbuffered overlapped I/O using per-context
+  I/O completion ports.
 
 Examples:
     >>> from zvec.typing import IOBackendType
@@ -157,7 +159,8 @@ Enumeration of supported I/O backend types for DiskAnn disk reads.
 )pbdoc")
       .value("PREAD", ailego::IOBackendType::kPread)
       .value("LIBAIO", ailego::IOBackendType::kLibAio)
-      .value("IO_URING", ailego::IOBackendType::kIoUring);
+      .value("IO_URING", ailego::IOBackendType::kIoUring)
+      .value("WINDOWS_OVERLAPPED", ailego::IOBackendType::kWindowsOverlapped);
 }
 
 void ZVecPyTyping::bind_status(py::module_ &m) {