Add documentation

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

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:
 

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