feat(diskann): add macOS POSIX AIO support

CMakeLists.txt

@@ -122,14 +122,18 @@ 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), using libaio when available
+#     and synchronous pread otherwise
+#   - macOS (x86_64, ARM64/Apple Silicon), using POSIX AIO with aio_suspend
+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/x86_64/ARM64 and macOS")
 endif()
 message(STATUS "DISKANN_SUPPORTED: ${DISKANN_SUPPORTED}")
 

examples/c/diskann_example.c

@@ -21,8 +21,10 @@
  * a Vamana graph structure combined with product quantization (PQ) to
  * achieve high recall with efficient disk I/O.
  *
- * NOTE: DiskANN requires Linux x86_64 with libaio. On other platforms the
- * example will compile but the runtime plugin will fail to load.
+ * NOTE: DiskANN supports Linux x86/x86_64/ARM64 (libaio when available,
+ * synchronous pread fallback otherwise) and macOS (POSIX AIO with
+ * aio_suspend()).
+ * Schema validation rejects DiskANN on other platforms.
  *
  * Workflow demonstrated:
  *   1. Create collection schema with DiskANN-indexed vector field
@@ -265,9 +267,6 @@ int main(void) {
                                 &results, &result_count);
   if (error != ZVEC_OK) {
     handle_error(error, "executing DiskANN query");
-    printf(
-        "  (This is expected on non-Linux platforms — DiskANN requires "
-        "libaio)\n");
   } else {
     printf("  Query returned %zu results:\n", result_count);
     for (size_t r = 0; r < result_count && r < 5; r++) {

python/tests/detail/fixture_helper.py

@@ -2,11 +2,10 @@
 import logging
 import platform
 
-DISKANN_SUPPORTED = platform.system() == "Linux" and platform.machine() in (
-    "x86_64",
-    "AMD64",
-    "i686",
-    "i386",
+_MACHINE = platform.machine().lower()
+DISKANN_SUPPORTED = platform.system() == "Darwin" or (
+    platform.system() == "Linux"
+    and _MACHINE in ("x86_64", "amd64", "i686", "i386", "aarch64", "arm64")
 )
 
 from typing import Any, Generator
@@ -27,7 +26,9 @@ 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/x86_64/ARM64 and macOS"
+        )
         return _DISKANN_PRELOAD_REASON
 
     _DISKANN_PRELOAD_REASON = None

python/tests/test_collection_diskann.py

@@ -15,16 +15,13 @@
 
 Mirrors ``test_collection_hnsw_rabitq.py`` but targets the DiskAnn index.
 
-Two platform-level prerequisites are enforced at module import time:
+Platform behavior:
 
-1. DiskAnn is currently built only for Linux x86_64 — 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.
+1. Linux x86/x86_64/ARM64 probes libaio at runtime and falls back to
+   synchronous pread() when libaio is unavailable.
+2. macOS uses the system POSIX AIO implementation with aio_suspend() waits.
 
-If either prerequisite fails the whole module is skipped so the rest of the
-test-suite is not affected.
+The module is skipped on platforms where DiskAnn is not built.
 """
 
 from __future__ import annotations
@@ -38,9 +35,14 @@
 # --------------------------------------------------------------------------- #
 # Platform gating (must happen BEFORE we touch zvec).
 # --------------------------------------------------------------------------- #
+_machine = platform.machine().lower()
+_diskann_supported = sys.platform == "darwin" or (
+    sys.platform == "linux"
+    and _machine in ("x86_64", "amd64", "i686", "i386", "aarch64", "arm64")
+)
 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 _diskann_supported,
+    reason="DiskAnn is supported on Linux x86/x86_64/ARM64 and macOS",
 )
 
 import zvec  # noqa: E402

python/tests/test_typing.py

@@ -34,6 +34,7 @@
         (DataType.FLOAT, "FLOAT"),
         (IndexType.HNSW, "HNSW"),
         (IOBackendType.PREAD, "PREAD"),
+        (IOBackendType.POSIX_AIO, "POSIX_AIO"),
         (MetricType.COSINE, "COSINE"),
         (QuantizeType.INT8, "INT8"),
         (StatusCode.OK, "OK"),
@@ -49,6 +50,7 @@ def test_enum_names(member, name):
         (DataType.FLOAT, 8),
         (IndexType.HNSW, 1),
         (IOBackendType.PREAD, 0),
+        (IOBackendType.POSIX_AIO, 2),
         (MetricType.COSINE, 3),
         (QuantizeType.INT8, 2),
         (StatusCode.OK, 0),
@@ -112,7 +114,7 @@ def test_index_type_has_member(member):
     assert member in IndexType.__members__
 
 
-@pytest.mark.parametrize("member", ["PREAD", "LIBAIO"])
+@pytest.mark.parametrize("member", ["PREAD", "LIBAIO", "POSIX_AIO"])
 def test_io_backend_type_has_member(member):
     assert member in IOBackendType.__members__
 

python/zvec/__init__.pyi

@@ -52,6 +52,7 @@ from .zvec import create_and_open, init, open
 def io_backend_type() -> IOBackendType:
     """Returns the current I/O backend type for DiskAnn async disk reads
     as an IOBackendType enum (zvec.typing.IOBackendType).
+    On macOS this is IOBackendType.POSIX_AIO. On Linux this is
     IOBackendType.LIBAIO if libaio is available, IOBackendType.PREAD otherwise."""
 
 def io_backend_description() -> str:

python/zvec/typing/__init__.pyi

@@ -130,6 +130,7 @@ class IOBackendType:
 
     - PREAD: Synchronous pread() — no async I/O.
     - LIBAIO: libaio loaded at runtime via dlopen().
+    - POSIX_AIO: macOS POSIX AIO with aio_suspend() completion waits.
 
     Examples:
         >>> from zvec.typing import IOBackendType
@@ -142,13 +143,16 @@ class IOBackendType:
       PREAD
 
       LIBAIO
+
+      POSIX_AIO
     """
 
     LIBAIO: typing.ClassVar[IOBackendType]  # value = <IOBackendType.LIBAIO: 1>
+    POSIX_AIO: typing.ClassVar[IOBackendType]  # value = <IOBackendType.POSIX_AIO: 2>
     PREAD: typing.ClassVar[IOBackendType]  # value = <IOBackendType.PREAD: 0>
     __members__: typing.ClassVar[
         dict[str, IOBackendType]
-    ]  # value = {'PREAD': <IOBackendType.PREAD: 0>, 'LIBAIO': <IOBackendType.LIBAIO: 1>}
+    ]  # value = {'PREAD': <IOBackendType.PREAD: 0>, 'LIBAIO': <IOBackendType.LIBAIO: 1>, 'POSIX_AIO': <IOBackendType.POSIX_AIO: 2>}
 
     def __eq__(self, other: typing.Any) -> bool: ...
     def __getstate__(self) -> int: ...

src/ailego/io/io_backend_def.h

@@ -32,6 +32,10 @@
 #include <ailego/io/libaio_loader.h>
 #include <zvec/ailego/io/io_backend.h>
 
+#if defined(__APPLE__)
+#include <TargetConditionals.h>
+#endif
+
 namespace zvec {
 namespace ailego {
 
@@ -40,31 +44,40 @@ inline const char *IOBackendTypeName(IOBackendType type) {
   switch (type) {
     case IOBackendType::kLibAio:
       return "libaio";
+    case IOBackendType::kPosixAio:
+      return "posix_aio";
     case IOBackendType::kPread:
       return "pread";
   }
   return "unknown";
 }
 
 // Returns a human-readable description for the given backend type.
-// When the backend is kPread, includes installation guidance for libaio.
+// On Linux, the kPread description includes installation guidance for libaio.
 inline const char *IOBackendDescription(IOBackendType type) {
   switch (type) {
     case IOBackendType::kLibAio:
       return "libaio async I/O backend loaded at runtime via dlopen().";
+    case IOBackendType::kPosixAio:
+      return "macOS POSIX AIO backend with aio_suspend() completion waits.";
     case IOBackendType::kPread:
+#if defined(__linux) || defined(__linux__)
       return "No async I/O backend available. Install libaio (e.g. "
              "'apt-get install libaio1', or 'libaio1t64' on Ubuntu 24.04+) "
              "and retry. DiskAnn will fall back to synchronous pread() \u2014 "
              "performance will be degraded.";
+#else
+      return "Synchronous pread() backend; no async I/O backend is "
+             "available.";
+#endif
   }
   return "Unknown I/O backend.";
 }
 
 // Singleton that loads and queries an I/O backend on demand.
 //
-// available() (no arg) tries the best backend with priority (libaio > pread)
-// and returns the loaded backend type.
+// available() (no arg) returns the platform backend. On Linux it tries libaio
+// before falling back to pread; on macOS POSIX AIO is provided by the system.
 // available(IOBackendType) tries a specific backend.
 // Use type() / name() to query the loaded backend without triggering a load.
 class IOBackend {
@@ -74,8 +87,8 @@ class IOBackend {
     return instance;
   }
 
-  // Try to load the best available backend (libaio > pread).
-  // Returns the loaded backend type.
+  // Return the selected platform backend. Linux probes libaio before falling
+  // back to pread; macOS uses the system POSIX AIO backend.
   // Idempotent — if already loaded, returns immediately.
   IOBackendType available() {
     if (type_ != IOBackendType::kPread) {
@@ -84,13 +97,19 @@ class IOBackend {
     return available(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).
+  // Try to load the requested backend. Returns the selected backend type,
+  // which may differ from the request when it is unavailable on this platform.
   // Idempotent — if the same backend is already loaded, returns immediately.
   IOBackendType available(IOBackendType requested) {
     if (type_ == requested && type_ != IOBackendType::kPread) {
       return type_;
     }
+#if defined(__APPLE__) && TARGET_OS_OSX
+    // POSIX AIO is provided by Darwin; no user-installed runtime dependency
+    // needs to be probed.
+    type_ = IOBackendType::kPosixAio;
+    return type_;
+#endif
 #if defined(__linux) || defined(__linux__)
     if (requested == IOBackendType::kLibAio) {
       if (LibAioLoader::Instance().load() &&
@@ -112,6 +131,10 @@ class IOBackend {
     return available() == IOBackendType::kLibAio;
   }
 
+  bool is_posix_aio() {
+    return available() == IOBackendType::kPosixAio;
+  }
+
   // Returns the loaded backend type.
   IOBackendType type() const {
     return type_;
@@ -130,7 +153,13 @@ class IOBackend {
  private:
   IOBackend() = default;
 
-  IOBackendType type_{IOBackendType::kPread};
+  IOBackendType type_{
+#if defined(__APPLE__) && TARGET_OS_OSX
+      IOBackendType::kPosixAio
+#else
+      IOBackendType::kPread
+#endif
+  };
 };
 
 }  // namespace ailego

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

@@ -228,7 +228,8 @@ void ZVecPyConfig::Initialize(pybind11::module_ &m) {
       },
       "Returns the current I/O backend type for DiskAnn async disk reads "
       "as an IOBackendType enum (zvec.typing.IOBackendType). "
-      "IOBackendType.LIBAIO if libaio is available, "
+      "On macOS this is IOBackendType.POSIX_AIO; on Linux this is "
+      "IOBackendType.LIBAIO when libaio is available and "
       "IOBackendType.PREAD otherwise.");
 
   // Returns a human-readable description of the I/O backend, including
@@ -242,4 +243,4 @@ void ZVecPyConfig::Initialize(pybind11::module_ &m) {
 }
 
 
-}  // namespace zvec
+}  // namespace zvec

src/binding/python/typing/python_type.cc

@@ -146,14 +146,16 @@ Enumeration of supported I/O backend types for DiskAnn async disk reads.
 
 - PREAD: Synchronous pread() \u2014 no async I/O.
 - LIBAIO: libaio loaded at runtime via dlopen().
+- POSIX_AIO: macOS POSIX AIO with aio_suspend() completion waits.
 
 Examples:
     >>> from zvec.typing import IOBackendType
     >>> print(IOBackendType.LIBAIO)
     IOBackendType.LIBAIO
 )pbdoc")
       .value("PREAD", ailego::IOBackendType::kPread)
-      .value("LIBAIO", ailego::IOBackendType::kLibAio);
+      .value("LIBAIO", ailego::IOBackendType::kLibAio)
+      .value("POSIX_AIO", ailego::IOBackendType::kPosixAio);
 }
 
 void ZVecPyTyping::bind_status(py::module_ &m) {
@@ -245,4 +247,4 @@ Construct a status with the given code and optional message.
       });
 }
 
-}  // namespace zvec
+}  // namespace zvec

src/core/CMakeLists.txt

@@ -74,7 +74,8 @@ if(NOT DISKANN_SUPPORTED)
 endif()
 
 set(ZVEC_CORE_LIBS zvec_ailego zvec_turbo sparsehash magic_enum rabitqlib)
-# The DiskAnn runtime loader uses dlopen/dlsym, so link libdl on Linux.
+# The DiskAnn runtime loader (LibAioLoader) uses dlopen/dlsym, so link libdl
+# on Linux. On macOS, POSIX AIO is provided by the system.
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
   list(APPEND ZVEC_CORE_LIBS ${CMAKE_DL_LIBS})
 endif()

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/x86_64/ARM64 and macOS\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()