Singleton class of default values used throughout KvikIO. More...

#include <defaults.hpp>

Static Public Member Functions
static CompatMode	compat_mode ()
	Return whether the KvikIO library is running in compatibility mode or not. More...

static void	set_compat_mode (CompatMode compat_mode)
	Set the value of `kvikio::defaults::compat_mode()`. More...

static CompatMode	infer_compat_mode_if_auto (CompatMode compat_mode) noexcept
	Infer the `AUTO` compatibility mode from the system runtime. More...

static bool	is_compat_mode_preferred (CompatMode compat_mode) noexcept
	Given a requested compatibility mode, whether it is expected to reduce to `ON`. More...

static bool	is_compat_mode_preferred ()
	Whether the global compatibility mode from class defaults is expected to be `ON`. More...

static BS_thread_pool &	thread_pool ()
	Get the default thread pool. More...

static unsigned int	thread_pool_nthreads ()
	Get the number of threads in the default thread pool. More...

static void	set_thread_pool_nthreads (unsigned int nthreads)
	Set the number of threads in the default thread pool. Waits for all currently running tasks to be completed, then destroys all threads in the pool and creates a new thread pool with the new number of threads. Any tasks that were waiting in the queue before the pool was reset will then be executed by the new threads. More...

static unsigned int	num_threads ()
	Alias of `thread_pool_nthreads` More...

static void	set_num_threads (unsigned int nthreads)
	Alias of `set_thread_pool_nthreads` More...

static std::size_t	task_size ()
	Get the default task size used for parallel IO operations. More...

static void	set_task_size (std::size_t nbytes)
	Set the default task size used for parallel IO operations. More...

static std::size_t	gds_threshold ()
	Get the default GDS threshold, which is the minimum size to use GDS (in bytes). More...

static void	set_gds_threshold (std::size_t nbytes)
	Set the default GDS threshold, which is the minimum size to use GDS (in bytes). More...

static std::size_t	bounce_buffer_size ()
	Get the size of the bounce buffer used to stage data in host memory. More...

static void	set_bounce_buffer_size (std::size_t nbytes)
	Set the size of the bounce buffer used to stage data in host memory. More...

static std::size_t	http_max_attempts ()
	Get the maximum number of attempts per remote IO read. More...

static void	set_http_max_attempts (std::size_t attempts)
	Set the maximum number of attempts per remote IO read. More...

static long	http_timeout ()
	The maximum time, in seconds, the transfer is allowed to complete. More...

static void	set_http_timeout (long timeout_seconds)
	Reset the http timeout. More...

static std::vector< int > const &	http_status_codes ()
	The list of HTTP status codes to retry. More...

static void	set_http_status_codes (std::vector< int > status_codes)
	Set the list of HTTP status codes to retry. More...

Detailed Description

Singleton class of default values used throughout KvikIO.

Definition at line 123 of file defaults.hpp.

Member Function Documentation

◆ bounce_buffer_size()

static std::size_t kvikio::defaults::bounce_buffer_size ( )

static

Get the size of the bounce buffer used to stage data in host memory.

Set the value using kvikio::default::set_bounce_buffer_size() or by setting the KVIKIO_BOUNCE_BUFFER_SIZE environment variable. If not set, the value is 16 MiB.

Returns: The bounce buffer size in bytes.

◆ compat_mode()

static CompatMode kvikio::defaults::compat_mode ( )

static

Return whether the KvikIO library is running in compatibility mode or not.

Notice, this is not the same as the compatibility mode in cuFile. That is, cuFile can run in compatibility mode while KvikIO is not.

When KvikIO is running in compatibility mode, it doesn't load libcufile.so. Instead, reads and writes are done using POSIX.

Set the environment variable KVIKIO_COMPAT_MODE to enable/disable compatibility mode. By default, compatibility mode is enabled:

when libcufile cannot be found
when running in Windows Subsystem for Linux (WSL)
when /run/udev isn't readable, which typically happens when running inside a docker image not launched with --volume /run/udev:/run/udev:ro

Returns: Compatibility mode.

◆ gds_threshold()

static std::size_t kvikio::defaults::gds_threshold ( )

static

Get the default GDS threshold, which is the minimum size to use GDS (in bytes).

In order to improve performance of small IO, .pread() and .pwrite() implement a shortcut that circumvent the threadpool and use the POSIX backend directly.

Set the default value using kvikio::default::set_gds_threshold() or by setting the KVIKIO_GDS_THRESHOLD environment variable. If not set, the default value is 1 MiB.

Returns: The default GDS threshold size in bytes.

◆ http_max_attempts()

static std::size_t kvikio::defaults::http_max_attempts ( )

static

Get the maximum number of attempts per remote IO read.

Set the value using kvikio::default::set_http_max_attempts() or by setting the KVIKIO_HTTP_MAX_ATTEMPTS environment variable. If not set, the value is 3.

Returns: The maximum number of remote IO reads to attempt before raising an error.

◆ http_status_codes()

static std::vector<int> const& kvikio::defaults::http_status_codes ( )

static

The list of HTTP status codes to retry.

Set the value using kvikio::default::set_http_status_codes() or by setting the KVIKIO_HTTP_STATUS_CODES environment variable. If not set, the default value is

429
500
502
503
504

Returns: The list of HTTP status codes to retry.

◆ http_timeout()

static long kvikio::defaults::http_timeout ( )

static

The maximum time, in seconds, the transfer is allowed to complete.

Set the value using kvikio::default::set_http_timeout() or by setting the KVIKIO_HTTP_TIMEOUT environment variable. If not set, the value is 60.

Returns: The maximum time the transfer is allowed to complete.

◆ infer_compat_mode_if_auto()

static CompatMode kvikio::defaults::infer_compat_mode_if_auto ( CompatMode compat_mode )

staticnoexcept

Infer the AUTO compatibility mode from the system runtime.

If the requested compatibility mode is AUTO, set the expected compatibility mode to ON or OFF by performing a system config check; otherwise, do nothing. Effectively, this function reduces the requested compatibility mode from three possible states (ON/OFF/AUTO) to two (ON/OFF) so as to determine the actual I/O path. This function is lightweight as the inferred result is cached.

◆ is_compat_mode_preferred() [1/2]

static bool kvikio::defaults::is_compat_mode_preferred ( )

static

Whether the global compatibility mode from class defaults is expected to be ON.

This function returns true if any of the two condition is satisfied:

The compatibility mode is ON.
It is AUTO but inferred to be ON.

Conceptually, the opposite of this function is whether the global compatibility mode is expected to be OFF, which would occur if any of the two condition is satisfied:

The compatibility mode is OFF.
It is AUTO but inferred to be OFF.

Returns: Boolean answer.

◆ is_compat_mode_preferred() [2/2]

static bool kvikio::defaults::is_compat_mode_preferred ( CompatMode compat_mode )

staticnoexcept

Given a requested compatibility mode, whether it is expected to reduce to ON.

This function returns true if any of the two condition is satisfied:

The compatibility mode is ON.
It is AUTO but inferred to be ON.

Conceptually, the opposite of this function is whether requested compatibility mode is expected to be OFF, which would occur if any of the two condition is satisfied:

The compatibility mode is OFF.
It is AUTO but inferred to be OFF.

Parameters

compat_mode Compatibility mode.

Returns: Boolean answer.

◆ num_threads()

static unsigned int kvikio::defaults::num_threads ( )

static

Alias of thread_pool_nthreads

Returns: The number of threads

◆ set_bounce_buffer_size()

static void kvikio::defaults::set_bounce_buffer_size ( std::size_t nbytes )

static

Set the size of the bounce buffer used to stage data in host memory.

Parameters

nbytes The bounce buffer size in bytes.

◆ set_compat_mode()

static void kvikio::defaults::set_compat_mode ( CompatMode compat_mode )

static

Set the value of kvikio::defaults::compat_mode().

Changing the compatibility mode affects all the new FileHandles whose compat_mode argument is not explicitly set, but it never affects existing FileHandles.

Parameters

compat_mode Compatibility mode.

◆ set_gds_threshold()

static void kvikio::defaults::set_gds_threshold ( std::size_t nbytes )

static

Set the default GDS threshold, which is the minimum size to use GDS (in bytes).

Parameters

nbytes The default GDS threshold size in bytes.

◆ set_http_max_attempts()

static void kvikio::defaults::set_http_max_attempts ( std::size_t attempts )

static

Set the maximum number of attempts per remote IO read.

Parameters

attempts The maximum number of attempts to try before raising an error.

◆ set_http_status_codes()

static void kvikio::defaults::set_http_status_codes ( std::vector< int > status_codes )

static

Set the list of HTTP status codes to retry.

Parameters

status_codes The HTTP status codes to retry.

◆ set_http_timeout()

static void kvikio::defaults::set_http_timeout ( long timeout_seconds )

static

Reset the http timeout.

Parameters

timeout_seconds The maximum time the transfer is allowed to complete.

◆ set_num_threads()

static void kvikio::defaults::set_num_threads ( unsigned int nthreads )

static

Alias of set_thread_pool_nthreads

Parameters

nthreads The number of threads to use

◆ set_task_size()

static void kvikio::defaults::set_task_size ( std::size_t nbytes )

static

Set the default task size used for parallel IO operations.

Parameters

nbytes The default task size in bytes.

◆ set_thread_pool_nthreads()

static void kvikio::defaults::set_thread_pool_nthreads ( unsigned int nthreads )

static

Set the number of threads in the default thread pool. Waits for all currently running tasks to be completed, then destroys all threads in the pool and creates a new thread pool with the new number of threads. Any tasks that were waiting in the queue before the pool was reset will then be executed by the new threads.

Parameters

nthreads The number of threads to use.

◆ task_size()

static std::size_t kvikio::defaults::task_size ( )

static

Get the default task size used for parallel IO operations.

Set the default value using kvikio::default::set_task_size() or by setting the KVIKIO_TASK_SIZE environment variable. If not set, the default value is 4 MiB.

Returns: The default task size in bytes.

◆ thread_pool()

static BS_thread_pool& kvikio::defaults::thread_pool ( )

static

Get the default thread pool.

Notice, it is not possible to change the default thread pool. KvikIO will always use the same thread pool however it is possible to change number of threads in the pool (see kvikio::default::set_thread_pool_nthreads()).

Returns: The default thread pool instance.

◆ thread_pool_nthreads()

static unsigned int kvikio::defaults::thread_pool_nthreads ( )

static

Get the number of threads in the default thread pool.

Set the default value using kvikio::default::set_thread_pool_nthreads() or by setting the KVIKIO_NTHREADS environment variable. If not set, the default value is 1.

Returns: The number of threads.

The documentation for this class was generated from the following file:

defaults.hpp

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ bounce_buffer_size()

◆ compat_mode()

◆ gds_threshold()

◆ http_max_attempts()

◆ http_status_codes()

◆ http_timeout()

◆ infer_compat_mode_if_auto()

◆ is_compat_mode_preferred() [1/2]

◆ is_compat_mode_preferred() [2/2]

◆ num_threads()

◆ set_bounce_buffer_size()

◆ set_compat_mode()

◆ set_gds_threshold()

◆ set_http_max_attempts()

◆ set_http_status_codes()

◆ set_http_timeout()

◆ set_num_threads()

◆ set_task_size()

◆ set_thread_pool_nthreads()

◆ task_size()

◆ thread_pool()

◆ thread_pool_nthreads()