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">nightly (25.04)</div><div class="rapids-selector__menu"><a class="rapids-selector__menu-item rapids-selector__menu-item--selected" href="/api/libkvikio/nightly">nightly (25.04)</a><a class="rapids-selector__menu-item" 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.</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> <h3><a class="anchor" id="autotoc_md16"></a> HTTP Retries</h3> <p>The behavior when a remote IO read returns a error can be controlled through the <code>KVIKIO_HTTP_STATUS_CODES</code> and <code>KVIKIO_HTTP_MAX_ATTEMPTS</code> environment variables. <code>KVIKIO_HTTP_STATUS_CODES</code> controls the status codes to retry, and <code>KVIKIO_HTTP_MAX_ATTEMPTS</code> controls the maximum number of attempts to make before throwing an exception.</p> <p>When a response with a status code in the list of retryable codes is received, KvikIO will wait for some period of time before retrying the request. It will keep retrying until reaching the maximum number of attempts.</p> <p>By default, KvikIO will retry responses with the following status codes:</p> <ul> <li>429</li> <li>500</li> <li>502</li> <li>503</li> <li>504</li> </ul> <p>KvikIO will, by default, make three attempts per read. Note that if you're reading a large file that has been split into multiple reads through the KvikIO's task size setting, then <em>each</em> task will be retried up to the maximum number of attempts.</p> <p>These settings can also be controlled by <code>defaults::http_max_attempts()</code>, <code>defaults::http_max_attempts_reset()</code>, <code>defaults::http_status_codes()</code>, and <code>defaults::http_status_codes_reset()</code>.</p> <h1><a class="anchor" id="autotoc_md17"></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/nightly/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/nightly/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/nightly/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/nightly/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/nightly/file__handle_8hpp_source#l00047'>file_handle.hpp:47</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>