feat(diskann): add macOS support via kqueue-based async IO

.github/workflows/03-macos-linux-build.yml

@@ -203,7 +203,6 @@ jobs:
           cd "$GITHUB_WORKSPACE"
           python -m pytest python/tests/test_collection_diskann.py -v
         shell: bash
-
       # Verify installing libaio does not affect existing non-DiskAnn tests.
       - name: Run HNSW Tests (w/ libaio)
         if: matrix.platform == 'linux-x64'

CMakeLists.txt

@@ -122,14 +122,17 @@ else()
 endif()
 message(STATUS "RABITQ_ARCH_FLAG: ${RABITQ_ARCH_FLAG}")
 
-# DiskAnn support (Linux x86_64 only; libaio loaded at runtime via dlopen)
-if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|i686|i386" AND NOT ANDROID AND NOT IOS)
+# DiskAnn support:
+#   - Linux (x86_64, i686, i386, aarch64, arm64) with libaio (loaded via dlopen)
+#   - macOS (x86_64, ARM64/Apple Silicon) with kqueue
+if((CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|i686|i386|aarch64|arm64" AND NOT ANDROID AND NOT IOS)
+    OR (CMAKE_SYSTEM_NAME STREQUAL "Darwin" AND NOT IOS))
   set(DISKANN_SUPPORTED ON)
   add_definitions(-DDISKANN_SUPPORTED=1)
 else()
   set(DISKANN_SUPPORTED OFF)
   add_definitions(-DDISKANN_SUPPORTED=0)
-  message(STATUS "DiskAnn support disabled - only supported on Linux x86_64")
+  message(STATUS "DiskAnn support disabled - supported on Linux (x86_64/ARM64 with libaio) and macOS (with kqueue)")
 endif()
 message(STATUS "DISKANN_SUPPORTED: ${DISKANN_SUPPORTED}")
 

examples/c++/CMakeLists.txt

@@ -15,6 +15,7 @@ endif()
 get_filename_component(ZVEC_ROOT_DIR "${CMAKE_CURRENT_LIST_DIR}/../.." ABSOLUTE)
 
 set(ZVEC_INCLUDE_DIR ${ZVEC_ROOT_DIR}/src/include)
+set(ZVEC_SRC_DIR ${ZVEC_ROOT_DIR}/src)
 set(ZVEC_LIB_DIR ${ZVEC_ROOT_DIR}/${HOST_BUILD_DIR}/lib)
 
 include_directories(${ZVEC_INCLUDE_DIR})

python/tests/detail/fixture_helper.py

@@ -2,12 +2,10 @@
 import logging
 import platform
 
-DISKANN_SUPPORTED = platform.system() == "Linux" and platform.machine() in (
-    "x86_64",
-    "AMD64",
-    "i686",
-    "i386",
-)
+DISKANN_SUPPORTED = (
+    platform.system() == "Linux"
+    and platform.machine() in ("x86_64", "AMD64", "i686", "i386", "aarch64", "arm64")
+) or platform.system() == "Darwin"
 
 from typing import Any, Generator
 from zvec.typing import DataType, StatusCode, MetricType, QuantizeType
@@ -27,9 +25,8 @@ def _ensure_diskann_runtime_or_reason() -> str | None:
     _DISKANN_PRELOAD_DONE = True
 
     if not DISKANN_SUPPORTED:
-        _DISKANN_PRELOAD_REASON = "DiskAnn only supported on Linux x86_64"
+        _DISKANN_PRELOAD_REASON = "DiskAnn is supported on Linux (x86_64/ARM64 with libaio) and macOS (kqueue)"
         return _DISKANN_PRELOAD_REASON
-
     _DISKANN_PRELOAD_REASON = None
     return None
 

python/tests/test_collection_diskann.py

@@ -17,8 +17,8 @@
 
 Two platform-level prerequisites are enforced at module import time:
 
-1. DiskAnn is currently built only for Linux x86_64 — other platforms are
-   skipped wholesale.
+1. DiskAnn is built for Linux (x86_64/ARM64 with libaio) and macOS (with kqueue) —
+   other platforms are skipped wholesale.
 2. libaio is loaded eagerly (via dlopen) inside DiskAnnBuilder::init() /
    DiskAnnStreamer::init(). If libaio is missing, DiskAnn falls back to
    synchronous pread() — the tests still run but with degraded performance.
@@ -39,8 +39,14 @@
 # Platform gating (must happen BEFORE we touch zvec).
 # --------------------------------------------------------------------------- #
 pytestmark = pytest.mark.skipif(
-    not (sys.platform == "linux" and platform.machine() in ("x86_64", "AMD64")),
-    reason="DiskAnn plugin is only supported on Linux x86_64",
+    not (
+        (
+            sys.platform == "linux"
+            and platform.machine() in ("x86_64", "AMD64", "aarch64", "arm64")
+        )
+        or sys.platform == "darwin"
+    ),
+    reason="DiskAnn is supported on Linux (x86_64/ARM64 with libaio) and macOS (kqueue)",
 )
 
 import zvec  # noqa: E402

src/ailego/io/io_backend_def.h

@@ -29,6 +29,7 @@
 
 #pragma once
 
+#include <mutex>
 #include <ailego/io/libaio_loader.h>
 #include <zvec/ailego/io/io_backend.h>
 
@@ -78,30 +79,16 @@ class IOBackend {
   // Returns the loaded backend type.
   // Idempotent — if already loaded, returns immediately.
   IOBackendType available() {
-    if (type_ != IOBackendType::kPread) {
-      return type_;
-    }
-    return available(IOBackendType::kLibAio);
+    std::lock_guard<std::mutex> lock(mutex_);
+    return available_locked(IOBackendType::kLibAio);
   }
 
   // Try to load the requested backend.  Returns the loaded backend type
   // (may differ from requested if the load failed — falls back to kPread).
   // Idempotent — if the same backend is already loaded, returns immediately.
   IOBackendType available(IOBackendType requested) {
-    if (type_ == requested && type_ != IOBackendType::kPread) {
-      return type_;
-    }
-#if defined(__linux) || defined(__linux__)
-    if (requested == IOBackendType::kLibAio) {
-      if (LibAioLoader::Instance().load() &&
-          LibAioLoader::Instance().is_available()) {
-        type_ = IOBackendType::kLibAio;
-        return type_;
-      }
-    }
-#endif
-    type_ = IOBackendType::kPread;
-    return type_;
+    std::lock_guard<std::mutex> lock(mutex_);
+    return available_locked(requested);
   }
 
   bool is_pread() {
@@ -114,22 +101,41 @@ class IOBackend {
 
   // Returns the loaded backend type.
   IOBackendType type() const {
+    std::lock_guard<std::mutex> lock(mutex_);
     return type_;
   }
 
   // Human-readable name for the selected backend.
   const char *name() const {
-    return IOBackendTypeName(type_);
+    return IOBackendTypeName(type());
   }
 
   // Human-readable description for the selected backend.
   const char *description() const {
-    return IOBackendDescription(type_);
+    return IOBackendDescription(type());
   }
 
  private:
   IOBackend() = default;
 
+  IOBackendType available_locked(IOBackendType requested) {
+    if (type_ == requested && type_ != IOBackendType::kPread) {
+      return type_;
+    }
+#if defined(__linux) || defined(__linux__)
+    if (requested == IOBackendType::kLibAio) {
+      if (LibAioLoader::Instance().load() &&
+          LibAioLoader::Instance().is_available()) {
+        type_ = IOBackendType::kLibAio;
+        return type_;
+      }
+    }
+#endif
+    type_ = IOBackendType::kPread;
+    return type_;
+  }
+
+  mutable std::mutex mutex_;
   IOBackendType type_{IOBackendType::kPread};
 };
 

src/binding/python/model/python_collection.cc

@@ -313,7 +313,16 @@ void ZVecPyCollection::bind_dql_methods(
           "given vector column. One of 'mmap', 'buffer_pool', 'contiguous'. "
           "Raises KeyError if no HNSW index exists on the column, or "
           "ValueError if the column's index is not an HNSW index. Intended "
-          "for introspection and testing only; not part of the stable API.");
+          "for introspection and testing only; not part of the stable API.")
+      .def(
+          "_debug_io_backend_type",
+          [](const Collection &self) {
+            const auto result = self.DebugGetIoBackendType();
+            return unwrap_expected(result);
+          },
+          "Debug-only: returns the I/O backend type used by DiskAnn. "
+          "One of 'libaio', 'pread'. Intended for introspection and "
+          "testing only; not part of the stable API.");
 }
 
 }  // namespace zvec

src/core/algorithm/CMakeLists.txt

@@ -17,7 +17,7 @@ else()
   # Empty stub library for unsupported platforms
   file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/diskann_stub.cc
     "// Stub implementation for unsupported platforms\n"
-    "// DiskAnn only supports Linux x86_64\n"
+    "// DiskAnn supports Linux (x86_64/ARM64 with libaio) and macOS (kqueue)\n"
     "namespace zvec { namespace core { /* empty namespace for compatibility */ } }\n"
   )
 

src/core/algorithm/diskann/CMakeLists.txt

@@ -14,7 +14,7 @@ file(GLOB_RECURSE ALL_SRCS *.cc *.c)
 # ${CMAKE_DL_LIBS} for dlopen/dlsym/dlclose.
 set(CORE_KNN_DISKANN_LIBS core_framework core_knn_cluster)
 
-if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|i686|i386")
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|i686|i386|aarch64|arm64")
     list(APPEND CORE_KNN_DISKANN_LIBS ${CMAKE_DL_LIBS})
 endif()
 
@@ -31,4 +31,4 @@ cc_library(
     INCS . ${PROJECT_ROOT_DIR}/src/core ${PROJECT_ROOT_DIR}/src/core/algorithm
     LDFLAGS "${CORE_KNN_DISKANN_LDFLAGS}"
     VERSION "${PROXIMA_ZVEC_VERSION}"
-)
+)