CINXE.COM

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head> <meta content="text/xhtml;charset=utf-8" http-equiv="Content-Type"> <meta content="IE=9" http-equiv="X-UA-Compatible"> <meta content="Doxygen 1.9.1" name="generator"> <meta content="width=device-width, initial-scale=1" name="viewport"> <title>libkvikio: Welcome to KvikIO's C++ documentation!</title> <link href="tabs.css" rel="stylesheet" type="text/css"> <script src="jquery.js" type="text/javascript"></script> <script src="dynsections.js" type="text/javascript"></script> <link href="search/search.css" rel="stylesheet" type="text/css"> <script src="search/searchdata.js" type="text/javascript"></script> <script src="search/search.js" type="text/javascript"></script> <link href="doxygen.css" rel="stylesheet" type="text/css">  <script defer src="https://docs.rapids.ai/assets/js/custom.js"></script> <link href="https://docs.rapids.ai/assets/css/custom.css" rel="stylesheet">  <link href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" id="rapids-fa-tag" rel="stylesheet"><script id="rapids-selector-pixel-src" src="https://assets.adobedtm.com/5d4962a43b79/814eb6e9b4e1/launch-4bc07f1e0b0b.min.js"></script><link href="/assets/css/custom.css" id="rapids-selector-css" rel="stylesheet"></head> <body> <div id="top"> <div id="titlearea"><div id="rapids-doxygen-container"><div class="rapids-home-container"><a class="rapids-home-container__home-btn" href="/api">Home</a></div><div class="rapids-selector__container rapids-selector--hidden"><div class="rapids-selector__selected">libkvikio</div><div class="rapids-selector__menu"><a class="rapids-selector__menu-item" href="/api/cucim/stable">cucim</a><a class="rapids-selector__menu-item" href="/api/cudf-java/stable">cudf-java</a><a class="rapids-selector__menu-item" href="/api/cudf/stable/">cudf</a><a class="rapids-selector__menu-item" href="/api/cugraph/stable">cugraph</a><a class="rapids-selector__menu-item" href="/api/cuml/stable">cuml</a><a class="rapids-selector__menu-item" href="/api/cuproj/stable">cuproj</a><a class="rapids-selector__menu-item" href="/api/cuspatial/stable">cuspatial</a><a class="rapids-selector__menu-item" href="/api/cuvs/stable">cuvs</a><a class="rapids-selector__menu-item" href="/api/cuxfilter/stable">cuxfilter</a><a class="rapids-selector__menu-item" href="/api/dask-cuda/stable">dask-cuda</a><a class="rapids-selector__menu-item" href="/api/dask-cudf/stable">dask-cudf</a><a class="rapids-selector__menu-item" href="/api/kvikio/stable">kvikio</a><a class="rapids-selector__menu-item" href="/api/libcudf/stable/namespacecudf/">libcudf</a><a class="rapids-selector__menu-item" href="/api/libcuml/stable">libcuml</a><a class="rapids-selector__menu-item" href="/api/libcuproj/stable">libcuproj</a><a class="rapids-selector__menu-item" href="/api/libcuspatial/stable">libcuspatial</a><a class="rapids-selector__menu-item rapids-selector__menu-item--selected" href="/api/libkvikio/stable">libkvikio</a><a class="rapids-selector__menu-item" href="/api/librmm/stable">librmm</a><a class="rapids-selector__menu-item" href="/api/libucxx/stable">libucxx</a><a class="rapids-selector__menu-item" href="/api/raft/stable">raft</a><a class="rapids-selector__menu-item" href="/api/rapids-cmake/stable">rapids-cmake</a><a class="rapids-selector__menu-item" href="/api/rmm/stable">rmm</a></div></div><div class="rapids-selector__container rapids-selector--hidden"><div class="rapids-selector__selected">stable (25.02)</div><div class="rapids-selector__menu"><a class="rapids-selector__menu-item" href="/api/libkvikio/nightly">nightly (25.04)</a><a class="rapids-selector__menu-item rapids-selector__menu-item--selected" href="/api/libkvikio/stable">stable (25.02)</a><a class="rapids-selector__menu-item" href="/api/libkvikio/legacy">legacy (24.12)</a></div></div></div> </div>   <script type="text/javascript"> /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); /* @license-end */ </script> <script src="menudata.js" type="text/javascript"></script> <script src="menu.js" type="text/javascript"></script> <script type="text/javascript"> /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ $(function() { initMenu('',true,false,'search.php','Search'); $(document).ready(function() { init_search(); }); }); /* @license-end */</script> <div id="main-nav"></div> </div>  <div id="MSearchSelectWindow" onkeydown="return searchBox.OnSearchSelectKey(event)" onmouseout="return searchBox.OnSearchSelectHide()" onmouseover="return searchBox.OnSearchSelectShow()"> </div>  <div id="MSearchResultsWindow"> <iframe frameborder="0" id="MSearchResults" name="MSearchResults" src="javascript:void(0)"> </iframe> </div> <div class="PageDoc"><div class="header"> <div class="headertitle"> <div class="title">Welcome to KvikIO's C++ documentation! </div> </div> </div> <div class="contents"> <div class="textblock"><p><a class="anchor" id="md_main_page"></a> KvikIO is a Python and C++ library for high performance file IO. It provides C++ and Python bindings to <a href="https://docs.nvidia.com/gpudirect-storage/api-reference-guide/index.html">cuFile</a> which enables <a href="https://developer.nvidia.com/blog/gpudirect-storage/">GPUDirect Storage (GDS)</a>. KvikIO also works efficiently when GDS isn't available and can read/write both host and device data seamlessly.</p> <p>KvikIO C++ is part of the <a href="https://rapids.ai/">RAPIDS</a> suite of open-source software libraries for GPU-accelerated data science.</p> <hr> <p> <b>Notice</b> this is the documentation for the C++ library. For the Python documentation, see under <a href="https://docs.rapids.ai/api/kvikio/nightly/">kvikio</a>.</p> <hr> <h1><a class="anchor" id="autotoc_md3"></a> Features</h1> <ul> <li>Object Oriented API.</li> <li>Exception handling.</li> <li>Concurrent reads and writes using an internal thread pool.</li> <li>Non-blocking API.</li> <li>Handle both host and device IO seamlessly.</li> </ul> <h1><a class="anchor" id="autotoc_md4"></a> Installation</h1> <p>For convenience we release Conda packages that makes it easy to include KvikIO in your CMake projects.</p> <h2><a class="anchor" id="autotoc_md5"></a> Conda/Mamba</h2> <p>We strongly recommend using <a href="https://github.com/mamba-org/mamba">mamba</a> in place of conda, which we will do throughout the documentation.</p> <p>Install the <b>stable release</b> from the <code>rapidsai</code> channel with the following: </p><div class="fragment"><div class="line"># Install in existing environment</div> <div class="line">mamba install -c rapidsai -c conda-forge libkvikio</div> <div class="line"># Create new environment (CUDA 12)</div> <div class="line">mamba create -n libkvikio-env -c rapidsai -c conda-forge cuda-version=12.8 libkvikio</div> <div class="line"># Create new environment (CUDA 11)</div> <div class="line">mamba create -n libkvikio-env -c rapidsai -c conda-forge cuda-version=11.8 libkvikio</div> </div><p>Install the <b>nightly release</b> from the <code>rapidsai-nightly</code> channel with the following:</p> <div class="fragment"><div class="line"># Install in existing environment</div> <div class="line">mamba install -c rapidsai-nightly -c conda-forge libkvikio</div> <div class="line"># Create new environment (CUDA 12)</div> <div class="line">mamba create -n libkvikio-env -c rapidsai-nightly -c conda-forge python=3.12 cuda-version=12.8 libkvikio</div> <div class="line"># Create new environment (CUDA 11)</div> <div class="line">mamba create -n libkvikio-env -c rapidsai-nightly -c conda-forge python=3.12 cuda-version=11.8 libkvikio</div> </div><hr> <p> <b>Notice</b> if the nightly install doesn't work, set <code>channel_priority: flexible</code> in your <code>.condarc</code>.</p> <hr> <h2><a class="anchor" id="autotoc_md8"></a> Include KvikIO in a CMake project</h2> <p>An example of how to include KvikIO in an existing CMake project can be found here: <a href="https://github.com/rapidsai/kvikio/blob/HEAD/cpp/examples/downstream/">https://github.com/rapidsai/kvikio/blob/HEAD/cpp/examples/downstream/</a>.</p> <h2><a class="anchor" id="autotoc_md9"></a> Build from source</h2> <p>To build the C++ example run:</p> <div class="fragment"><div class="line">./build.sh libkvikio</div> </div><p>Then run the example:</p> <div class="fragment"><div class="line">./examples/basic_io</div> </div><h1><a class="anchor" id="autotoc_md10"></a> Runtime Settings</h1> <h3><a class="anchor" id="autotoc_md11"></a> Compatibility Mode (KVIKIO_COMPAT_MODE)</h3> <p>When KvikIO is running in compatibility mode, it doesn't load <code>libcufile.so</code>. Instead, reads and writes are done using POSIX. Notice, this is not the same as the compatibility mode in cuFile. It is possible that KvikIO performs I/O in the non-compatibility mode by using the cuFile library, but the cuFile library itself is configured to operate in its own compatibility mode. For more details, refer to <a href="https://docs.nvidia.com/gpudirect-storage/api-reference-guide/index.html#cufile-compatibility-mode">cuFile compatibility mode</a> and <a href="https://docs.nvidia.com/gpudirect-storage/troubleshooting-guide/index.html#environment-variables">cuFile environment variables</a></p> <p>The environment variable <code>KVIKIO_COMPAT_MODE</code> has three options (case-insensitive):</p><ul> <li><code>ON</code> (aliases: <code>TRUE</code>, <code>YES</code>, <code>1</code>): Enable the compatibility mode.</li> <li><code>OFF</code> (aliases: <code>FALSE</code>, <code>NO</code>, <code>0</code>): Disable the compatibility mode, and enforce cuFile I/O. GDS will be activated if the system requirements for cuFile are met and cuFile is properly configured. However, if the system is not suited for cuFile, I/O operations under the <code>OFF</code> option may error out, crash or hang.</li> <li><code>AUTO</code>: Try cuFile I/O first, and fall back to POSIX I/O if the system requirements for cuFile are not met.</li> </ul> <p>Under <code>AUTO</code>, KvikIO falls back to the compatibility mode:</p><ul> <li>when <code>libcufile.so</code> cannot be found.</li> <li>when running in Windows Subsystem for Linux (WSL).</li> <li>when <code>/run/udev</code> isn't readable, which typically happens when running inside a docker image not launched with <code>--volume /run/udev:/run/udev:ro</code>.</li> </ul> <p>This setting can also be programmatically controlled by <code>defaults::set_compat_mode()</code> and <code>defaults::compat_mode_reset()</code>.</p> <h3><a class="anchor" id="autotoc_md12"></a> Thread Pool (KVIKIO_NTHREADS)</h3> <p>KvikIO can use multiple threads for IO automatically. Set the environment variable <code>KVIKIO_NTHREADS</code> to the number of threads in the thread pool. If not set, the default value is 1.</p> <p>This setting can also be controlled by <code>defaults::thread_pool_nthreads()</code> and <code>defaults::thread_pool_nthreads_reset()</code>.</p> <h3><a class="anchor" id="autotoc_md13"></a> Task Size (KVIKIO_TASK_SIZE)</h3> <p>KvikIO splits parallel IO operations into multiple tasks. Set the environment variable <code>KVIKIO_TASK_SIZE</code> to the maximum task size (in bytes). If not set, the default value is 4194304 (4 MiB).</p> <p>This setting can also be controlled by <code>defaults::task_size()</code> and <code>defaults::task_size_reset()</code>.</p> <h3><a class="anchor" id="autotoc_md14"></a> GDS Threshold (KVIKIO_GDS_THRESHOLD)</h3> <p>To improve performance of small IO requests, <code>.pread()</code> and <code>.pwrite()</code> implement a shortcut that circumvents the threadpool and uses the POSIX backend directly. Set the environment variable <code>KVIKIO_GDS_THRESHOLD</code> to the minimum size (in bytes) to use GDS. If not set, the default value is 1048576 (1 MiB).</p> <p>This setting can also be controlled by <code>defaults::gds_threshold()</code> and <code>defaults::gds_threshold_reset()</code>.</p> <h3><a class="anchor" id="autotoc_md15"></a> Size of the Bounce Buffer (KVIKIO_GDS_THRESHOLD)</h3> <p>KvikIO might have to use intermediate host buffers (one per thread) when copying between files and device memory. Set the environment variable <code>KVIKIO_BOUNCE_BUFFER_SIZE</code> to the size (in bytes) of these "bounce" buffers. If not set, the default value is 16777216 (16 MiB).</p> <p>This setting can also be controlled by <code>defaults::bounce_buffer_size()</code> and <code>defaults::bounce_buffer_size_reset()</code>.</p> <h1><a class="anchor" id="autotoc_md16"></a> Example</h1> <div class="fragment"><div class="line"><span class="preprocessor">#include <cstddef></span></div> <div class="line"><span class="preprocessor">#include <cuda_runtime.h></span></div> <div class="line"><span class="preprocessor">#include <kvikio/file_handle.hpp></span></div> <div class="line"><span class="keyword">using namespace </span>std;</div> <div class="line"> </div> <div class="line"><span class="keywordtype">int</span> main()</div> <div class="line">{</div> <div class="line"> <span class="comment">// Create two arrays `a` and `b`</span></div> <div class="line"> constexpr std::size_t size = 100;</div> <div class="line"> <span class="keywordtype">void</span> *a = <span class="keyword">nullptr</span>;</div> <div class="line"> <span class="keywordtype">void</span> *b = <span class="keyword">nullptr</span>;</div> <div class="line"> cudaMalloc(&a, size);</div> <div class="line"> cudaMalloc(&b, size);</div> <div class="line"> </div> <div class="line"> <span class="comment">// Write `a` to file</span></div> <div class="line"> <a class='code' href='/api/libkvikio/stable/classkvikio_1_1filehandle'>kvikio::FileHandle</a> fw(<span class="stringliteral">"test-file"</span>, <span class="stringliteral">"w"</span>);</div> <div class="line"> <span class="keywordtype">size_t</span> written = fw.write(a, size);</div> <div class="line"> fw.close();</div> <div class="line"> </div> <div class="line"> <span class="comment">// Read file into `b`</span></div> <div class="line"> <a class='code' href='/api/libkvikio/stable/classkvikio_1_1filehandle'>kvikio::FileHandle</a> fr(<span class="stringliteral">"test-file"</span>, <span class="stringliteral">"r"</span>);</div> <div class="line"> <span class="keywordtype">size_t</span> read = fr.read(b, size);</div> <div class="line"> fr.close();</div> <div class="line"> </div> <div class="line"> <span class="comment">// Read file into `b` in parallel using 16 threads</span></div> <div class="line"> kvikio::default_thread_pool::reset(16);</div> <div class="line"> {</div> <div class="line"> <a class='code' href='/api/libkvikio/stable/classkvikio_1_1filehandle'>kvikio::FileHandle</a> f(<span class="stringliteral">"test-file"</span>, <span class="stringliteral">"r"</span>);</div> <div class="line"> future<size_t> future = f.pread(b_dev, <span class="keyword">sizeof</span>(a), 0); <span class="comment">// Non-blocking</span></div> <div class="line"> <span class="keywordtype">size_t</span> read = future.get(); <span class="comment">// Blocking</span></div> <div class="line"> <span class="comment">// Notice, `f` closes automatically on destruction.</span></div> <div class="line"> }</div> <div class="line">}</div> <div class="ttc" id="aclasskvikio_1_1FileHandle_html"><div class="ttname"><a href='/api/libkvikio/stable/classkvikio_1_1filehandle'>kvikio::FileHandle</a></div><div class="ttdoc">Handle of an open file registered with cufile.</div><div class="ttdef"><b>Definition:</b> <a href='/api/libkvikio/stable/file__handle_8hpp_source#l00044'>file_handle.hpp:44</a></div></div> </div><p>For a full runnable example see <a href="https://github.com/rapidsai/kvikio/blob/HEAD/cpp/examples/basic_io.cpp">https://github.com/rapidsai/kvikio/blob/HEAD/cpp/examples/basic_io.cpp</a>. </p> </div></div> </div>  <hr class="footer"><address class="footer"><small> Generated by <a href='https://www.doxygen.org/'><img alt="doxygen" class="footer" height="31" src="doxygen.svg" width="104"></a> 1.9.1 </small></address> <script defer id="rapids-selector-js" src="/assets/js/custom.js"></script><script id="rapids-selector-pixel-invocation" type="text/javascript">_satellite.pageBottom();</script></body></html>