From 74f8f2a3715642d7d77c4fb0f1e26c7c8592e0c0 Mon Sep 17 00:00:00 2001
From: Serge van der Ree <Serge.vanderRee@shell.com>
Date: Fri, 12 Jul 2024 14:13:34 +0200
Subject: [PATCH] Add documentation

---
 docs/source/execution.rst      | 12 ++++++++++++
 docs/source/high-level-api.rst | 13 +++++++++++++
 include/zfp.h                  |  9 +++++----
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/docs/source/execution.rst b/docs/source/execution.rst
index 7a69cf2d6..7139eb7e8 100644
--- a/docs/source/execution.rst
+++ b/docs/source/execution.rst
@@ -125,6 +125,18 @@ in use.  Future versions of |zfp| may allow specifying how threads are
 mapped to chunks, whether to use static or dynamic scheduling, etc.
 
 
+CUDA Stream
+^^^^^^^^^^^
+
+By default, all CUDA operations are performed on the default stream (also
+known as stream '0'). Using :c:func:`zfp_stream_set_cuda_stream` the user
+can specify a different, non-0 stream. This allows for potential overlap
+between execution units. For instance, when compressing two buffers and
+copying the results back to the host, using different streams for each
+would enable the second compression kernel to start concurrently with the
+transfer of the compressed first buffer.
+
+
 .. _exec-mode:
 
 Fixed- vs. Variable-Rate Compression
diff --git a/docs/source/high-level-api.rst b/docs/source/high-level-api.rst
index 7819bb410..a5160e150 100644
--- a/docs/source/high-level-api.rst
+++ b/docs/source/high-level-api.rst
@@ -699,6 +699,13 @@ Execution Policy
 
 ----
 
+.. c:function:: cudaStream_t zfp_stream_cuda_stream(zfp_stream* stream)
+
+   Return the stream on which CUDA operations are performed.
+   See :c:func:`zfp_stream_set_cuda_stream`.
+
+----
+
 .. c:function:: zfp_bool zfp_stream_set_execution(zfp_stream* stream, zfp_exec_policy policy)
 
   Set :ref:`execution policy <execution>`.  If different from the previous
@@ -723,6 +730,12 @@ Execution Policy
   If zero, use one chunk per thread.  This function also sets the execution
   policy to OpenMP.  Upon success, :code:`zfp_true` is returned.
 
+----
+
+.. c:function:: zfp_bool zfp_stream_set_cuda_stream(zfp_stream* stream, cudaStream_t custream)
+
+   Set the CUDA stream on which all CUDA operations will be performed. This function
+   also sets the execution policy to CUDA. Upon success, :code:`zfp_true` is returned.
 
 .. _hl-func-config:
 
diff --git a/include/zfp.h b/include/zfp.h
index ad1c3d3ad..392670e45 100644
--- a/include/zfp.h
+++ b/include/zfp.h
@@ -94,7 +94,7 @@ typedef struct {
 #ifdef ZFP_WITH_CUDA
 /* CUDA execution parameters */
 typedef struct {
-  cudaStream_t stream; /* */
+  cudaStream_t stream;  /* The stream on which to perform all CUDA operations */
 } zfp_exec_params_cuda;
 #endif
 
@@ -394,7 +394,7 @@ zfp_stream_omp_chunk_size(
 #ifdef ZFP_WITH_CUDA
 /* cuda stream */
 cudaStream_t
-zfp_stream_cuda_stream(    /* cuda stream */
+zfp_stream_cuda_stream(
   const zfp_stream* stream /* compressed stream */
 );
 #endif
@@ -421,10 +421,11 @@ zfp_stream_set_omp_chunk_size(
 );
 
 #ifdef ZFP_WITH_CUDA
+/* set CUDA stream on which to perform all CUDA operations */
 zfp_bool
 zfp_stream_set_cuda_stream(
-  zfp_stream* zfp,
-  cudaStream_t custream
+  zfp_stream* zfp,       /* compressed stream */
+  cudaStream_t custream  /* cuda stream */
 );
 #endif