From ef43dbba6341719cf9bfe042598ad4f030e0be0c Mon Sep 17 00:00:00 2001 From: Lachlan Deakin Date: Wed, 21 Feb 2024 17:58:06 +1100 Subject: [PATCH] Add performance note to array async API docs --- src/array.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/array.rs b/src/array.rs index a286e093..152a07b4 100644 --- a/src/array.rs +++ b/src/array.rs @@ -143,6 +143,16 @@ pub type MaybeBytes = Option>; /// #### Async API /// With the `async` feature and an async store, there are equivalent methods to the sync API with an `async_` prefix. /// +///
+/// The async API is not as performant as sync API, mainly due to the decision to keep this crate runtime-agnostic. +///
+/// +/// This crate does not spawn tasks internally. +/// The implication is that methods like [`async_retrieve_array_subset`](Array::async_retrieve_array_subset) or [`async_retrieve_chunks`](Array::async_retrieve_chunks) do not parallelise over chunks and can be slow compared to the sync API (especially when they involve a large number of chunks). +/// It is possible to achieve similar performance to the sync API, but it is involved. +/// For example, instead of using [`async_retrieve_chunks`](Array::async_retrieve_chunks), multiple tasks executing [`async_retrieve_chunk_into_array_view`](Array::async_retrieve_chunk_into_array_view) could be spawned that output to a preallocated buffer. +// TODO: Add example in zarrs_tools and reference here, or just refer to how it is done in async_retrieve_chunks internally +/// /// ### Parallel Writing /// /// If a chunk is written more than once, its element values depend on whichever operation wrote to the chunk last.