Update docs

rapidsai · rapids-bot · Oct 3, 2024 · Oct 2, 2024 · Oct 2, 2024 · Oct 3, 2024
commit 4aedafc481f9d6d5a5b1016a19841687e225afc3
diff --git a/README.md b/README.md
@@ -15,9 +15,88 @@ The C++ library is header-only making it easy to include in [existing projects](
 * A Python [Zarr](https://zarr.readthedocs.io/en/stable/) backend for reading and writing GPU data to file seamlessly.
 * Concurrent reads and writes using an internal thread pool.
 * Non-blocking API.
-* Handle both host and device IO seamlessly.
+* Read/write to both host and device memory seamlessly.
 * Provides Python bindings to [nvCOMP](https://github.com/NVIDIA/nvcomp).
 
+
 ### Documentation
  * Python: <https://docs.rapids.ai/api/kvikio/nightly/>
  * C++: <https://docs.rapids.ai/api/libkvikio/nightly/>
+
+
+### Examples
+
+#### Python
+```python
+import cupy
+import kvikio
+
+def main(path):
+    a = cupy.arange(100)
+    f = kvikio.CuFile(path, "w")
+    # Write whole array to file
+    f.write(a)
+    f.close()
+
+    b = cupy.empty_like(a)
+    f = kvikio.CuFile(path, "r")
+    # Read whole array from file
+    f.read(b)
+    assert all(a == b)
+
+    # Use contexmanager
+    c = cupy.empty_like(a)
+    with kvikio.CuFile(path, "r") as f:
+        f.read(c)
+    assert all(a == c)
+
+    # Non-blocking read
+    d = cupy.empty_like(a)
+    with kvikio.CuFile(path, "r") as f:
+        future1 = f.pread(d[:50])
+        future2 = f.pread(d[50:], file_offset=d[:50].nbytes)
+        future1.get()  # Wait for first read
+        future2.get()  # Wait for second read
+    assert all(a == d)
+
+
+if __name__ == "__main__":
+    main("/tmp/kvikio-hello-world-file")
+```
+
+#### C++
+```c++
+#include <cstddef>
+#include <cuda_runtime.h>
+#include <kvikio/file_handle.hpp>
+using namespace std;
+
+int main()
+{
+  // Create two arrays `a` and `b`
+  constexpr std::size_t size = 100;
+  void *a = nullptr;
+  void *b = nullptr;
+  cudaMalloc(&a, size);
+  cudaMalloc(&b, size);
+
+  // Write `a` to file
+  kvikio::FileHandle fw("test-file", "w");
+  size_t written = fw.write(a, size);
+  fw.close();
+
+  // Read file into `b`
+  kvikio::FileHandle fr("test-file", "r");
+  size_t read = fr.read(b, size);
+  fr.close();
+
+  // Read file into `b` in parallel using 16 threads
+  kvikio::default_thread_pool::reset(16);
+  {
+    kvikio::FileHandle f("test-file", "r");
+    future<size_t> future = f.pread(b_dev, sizeof(a), 0);  // Non-blocking
+    size_t read = future.get(); // Blocking
+    // Notice, `f` closes automatically on destruction.
+  }
+}
+```