Common user-tunable settings for storing ntuples.

All page sink classes need to support the common options.

Definition at line 48 of file RNTupleWriteOptions.hxx.

Public Types
enum class	EImplicitMT { kOff , kDefault }

Public Member Functions
virtual	~RNTupleWriteOptions ()=default

virtual std::unique_ptr< RNTupleWriteOptions >	Clone () const

std::size_t	GetApproxZippedClusterSize () const

std::uint32_t	GetCompression () const

bool	GetEnablePageChecksums () const

bool	GetEnableSamePageMerging () const

std::size_t	GetInitialUnzippedPageSize () const

std::uint64_t	GetMaxKeySize () const

std::size_t	GetMaxUnzippedClusterSize () const

std::size_t	GetMaxUnzippedPageSize () const

std::size_t	GetPageBufferBudget () const

bool	GetUseBufferedWrite () const

bool	GetUseDirectIO () const

EImplicitMT	GetUseImplicitMT () const

std::size_t	GetWriteBufferSize () const

void	SetApproxZippedClusterSize (std::size_t val)

void	SetCompression (RCompressionSetting::EAlgorithm::EValues algorithm, int compressionLevel)

void	SetCompression (std::uint32_t val)

void	SetEnablePageChecksums (bool val)
	Note that turning off page checksums will also turn off the same page merging optimization (see tuning.md)

void	SetEnableSamePageMerging (bool val)

void	SetInitialUnzippedPageSize (std::size_t val)

void	SetMaxUnzippedClusterSize (std::size_t val)

void	SetMaxUnzippedPageSize (std::size_t val)

void	SetPageBufferBudget (std::size_t val)

void	SetUseBufferedWrite (bool val)

void	SetUseDirectIO (bool val)

void	SetUseImplicitMT (EImplicitMT val)

void	SetWriteBufferSize (std::size_t val)

Static Public Attributes
static constexpr std::uint64_t	kDefaultMaxKeySize = 0x4000'0000

Protected Attributes
std::size_t	fApproxZippedClusterSize = 128 * 1024 * 1024
	Approximation of the target compressed cluster size.

std::uint32_t	fCompression {RCompressionSetting::EDefaults::kUseGeneralPurpose}

bool	fEnablePageChecksums = true
	If set, checksums will be calculated and written for every page.

bool	fEnableSamePageMerging = true
	If set, identical pages are deduplicated and aliased on disk. Requires page checksums.

std::size_t	fInitialUnzippedPageSize = 256
	Initially, columns start with a page of this size.

std::uint64_t	fMaxKeySize = kDefaultMaxKeySize
	Specifies the max size of a payload storeable into a single TKey.

std::size_t	fMaxUnzippedClusterSize = 10 * fApproxZippedClusterSize
	Memory limit for committing a cluster: with very high compression ratio, we need a limit on how large the I/O buffer can grow during writing.

std::size_t	fMaxUnzippedPageSize = 1024 * 1024
	Pages can grow only to the given limit in bytes.

std::size_t	fPageBufferBudget = 0
	The maximum size that the sum of all page buffers used for writing into a persistent sink are allowed to use.

bool	fUseBufferedWrite = true
	Whether to use buffered writing (with RPageSinkBuf).

bool	fUseDirectIO = false
	Whether to use Direct I/O for writing.

EImplicitMT	fUseImplicitMT = EImplicitMT::kDefault
	Whether to use implicit multi-threading to compress pages. Only has an effect if buffered writing is turned on.

std::size_t	fWriteBufferSize = 4 * 1024 * 1024
	Buffer size to use for writing to files, must be a multiple of 4096 bytes.

#include <ROOT/RNTupleWriteOptions.hxx>

Inheritance diagram for ROOT::Experimental::RNTupleWriteOptions:

[legend]

Member Enumeration Documentation

◆ EImplicitMT

enum class ROOT::Experimental::RNTupleWriteOptions::EImplicitMT

strong

Enumerator
kOff
kDefault

Definition at line 50 of file RNTupleWriteOptions.hxx.

Constructor & Destructor Documentation

◆ ~RNTupleWriteOptions()

virtual ROOT::Experimental::RNTupleWriteOptions::~RNTupleWriteOptions ( )

virtualdefault

Member Function Documentation

◆ Clone()

std::unique_ptr< ROOT::Experimental::RNTupleWriteOptions > ROOT::Experimental::RNTupleWriteOptions::Clone ( ) const

virtual

Reimplemented in ROOT::Experimental::RNTupleWriteOptionsDaos.

Definition at line 50 of file RNTupleWriteOptions.cxx.

◆ GetApproxZippedClusterSize()

std::size_t ROOT::Experimental::RNTupleWriteOptions::GetApproxZippedClusterSize ( ) const

inline

Definition at line 113 of file RNTupleWriteOptions.hxx.

◆ GetCompression()

std::uint32_t ROOT::Experimental::RNTupleWriteOptions::GetCompression ( ) const

inline

Definition at line 106 of file RNTupleWriteOptions.hxx.

◆ GetEnablePageChecksums()

bool ROOT::Experimental::RNTupleWriteOptions::GetEnablePageChecksums ( ) const

inline

Definition at line 140 of file RNTupleWriteOptions.hxx.

◆ GetEnableSamePageMerging()

bool ROOT::Experimental::RNTupleWriteOptions::GetEnableSamePageMerging ( ) const

inline

Definition at line 150 of file RNTupleWriteOptions.hxx.

◆ GetInitialUnzippedPageSize()

std::size_t ROOT::Experimental::RNTupleWriteOptions::GetInitialUnzippedPageSize ( ) const

inline

Definition at line 119 of file RNTupleWriteOptions.hxx.

◆ GetMaxKeySize()

std::uint64_t ROOT::Experimental::RNTupleWriteOptions::GetMaxKeySize ( ) const

inline

Definition at line 153 of file RNTupleWriteOptions.hxx.

◆ GetMaxUnzippedClusterSize()

std::size_t ROOT::Experimental::RNTupleWriteOptions::GetMaxUnzippedClusterSize ( ) const

inline

Definition at line 116 of file RNTupleWriteOptions.hxx.

◆ GetMaxUnzippedPageSize()

std::size_t ROOT::Experimental::RNTupleWriteOptions::GetMaxUnzippedPageSize ( ) const

inline

Definition at line 122 of file RNTupleWriteOptions.hxx.

◆ GetPageBufferBudget()

std::size_t ROOT::Experimental::RNTupleWriteOptions::GetPageBufferBudget ( ) const

Definition at line 87 of file RNTupleWriteOptions.cxx.

◆ GetUseBufferedWrite()

bool ROOT::Experimental::RNTupleWriteOptions::GetUseBufferedWrite ( ) const

inline

Definition at line 128 of file RNTupleWriteOptions.hxx.

◆ GetUseDirectIO()

bool ROOT::Experimental::RNTupleWriteOptions::GetUseDirectIO ( ) const

inline

Definition at line 131 of file RNTupleWriteOptions.hxx.

◆ GetUseImplicitMT()

EImplicitMT ROOT::Experimental::RNTupleWriteOptions::GetUseImplicitMT ( ) const

inline

Definition at line 137 of file RNTupleWriteOptions.hxx.

◆ GetWriteBufferSize()

std::size_t ROOT::Experimental::RNTupleWriteOptions::GetWriteBufferSize ( ) const

inline

Definition at line 134 of file RNTupleWriteOptions.hxx.

◆ SetApproxZippedClusterSize()

void ROOT::Experimental::RNTupleWriteOptions::SetApproxZippedClusterSize ( std::size_t val )

Definition at line 55 of file RNTupleWriteOptions.cxx.

◆ SetCompression() [1/2]

void ROOT::Experimental::RNTupleWriteOptions::SetCompression	(	RCompressionSetting::EAlgorithm::EValues	algorithm,
		int	compressionLevel )

inline

Definition at line 108 of file RNTupleWriteOptions.hxx.

◆ SetCompression() [2/2]

void ROOT::Experimental::RNTupleWriteOptions::SetCompression ( std::uint32_t val )

inline

Definition at line 107 of file RNTupleWriteOptions.hxx.

◆ SetEnablePageChecksums()

void ROOT::Experimental::RNTupleWriteOptions::SetEnablePageChecksums ( bool val )

inline

Note that turning off page checksums will also turn off the same page merging optimization (see tuning.md)

Definition at line 142 of file RNTupleWriteOptions.hxx.

◆ SetEnableSamePageMerging()

void ROOT::Experimental::RNTupleWriteOptions::SetEnableSamePageMerging ( bool val )

Definition at line 79 of file RNTupleWriteOptions.cxx.

◆ SetInitialUnzippedPageSize()

void ROOT::Experimental::RNTupleWriteOptions::SetInitialUnzippedPageSize ( std::size_t val )

Definition at line 67 of file RNTupleWriteOptions.cxx.

◆ SetMaxUnzippedClusterSize()

void ROOT::Experimental::RNTupleWriteOptions::SetMaxUnzippedClusterSize ( std::size_t val )

Definition at line 61 of file RNTupleWriteOptions.cxx.

◆ SetMaxUnzippedPageSize()

void ROOT::Experimental::RNTupleWriteOptions::SetMaxUnzippedPageSize ( std::size_t val )

Definition at line 73 of file RNTupleWriteOptions.cxx.

◆ SetPageBufferBudget()

void ROOT::Experimental::RNTupleWriteOptions::SetPageBufferBudget ( std::size_t val )

inline

Definition at line 126 of file RNTupleWriteOptions.hxx.

◆ SetUseBufferedWrite()

void ROOT::Experimental::RNTupleWriteOptions::SetUseBufferedWrite ( bool val )

inline

Definition at line 129 of file RNTupleWriteOptions.hxx.

◆ SetUseDirectIO()

void ROOT::Experimental::RNTupleWriteOptions::SetUseDirectIO ( bool val )

inline

Definition at line 132 of file RNTupleWriteOptions.hxx.

◆ SetUseImplicitMT()

void ROOT::Experimental::RNTupleWriteOptions::SetUseImplicitMT ( EImplicitMT val )

inline

Definition at line 138 of file RNTupleWriteOptions.hxx.

◆ SetWriteBufferSize()

void ROOT::Experimental::RNTupleWriteOptions::SetWriteBufferSize ( std::size_t val )

inline

Definition at line 135 of file RNTupleWriteOptions.hxx.

Member Data Documentation

◆ fApproxZippedClusterSize

std::size_t ROOT::Experimental::RNTupleWriteOptions::fApproxZippedClusterSize = 128 * 1024 * 1024

protected

Approximation of the target compressed cluster size.

Definition at line 64 of file RNTupleWriteOptions.hxx.

◆ fCompression

std::uint32_t ROOT::Experimental::RNTupleWriteOptions::fCompression {RCompressionSetting::EDefaults::kUseGeneralPurpose}

protected

Definition at line 62 of file RNTupleWriteOptions.hxx.

◆ fEnablePageChecksums

bool ROOT::Experimental::RNTupleWriteOptions::fEnablePageChecksums = true

protected

If set, checksums will be calculated and written for every page.

Definition at line 94 of file RNTupleWriteOptions.hxx.

◆ fEnableSamePageMerging

bool ROOT::Experimental::RNTupleWriteOptions::fEnableSamePageMerging = true

protected

If set, identical pages are deduplicated and aliased on disk. Requires page checksums.

Definition at line 96 of file RNTupleWriteOptions.hxx.

◆ fInitialUnzippedPageSize

std::size_t ROOT::Experimental::RNTupleWriteOptions::fInitialUnzippedPageSize = 256

protected

Initially, columns start with a page of this size.

The default value is chosen to accomodate at least 32 elements of 64 bits, or 64 elements of 32 bits. If more elements are needed, pages are increased up until the byte limit given by fMaxUnzippedPageSize or until the total page buffer limit is reached (as a sum of all page buffers). The total write buffer limit needs to be large enough to hold the initial pages of all columns.

Definition at line 72 of file RNTupleWriteOptions.hxx.

◆ fMaxKeySize

std::uint64_t ROOT::Experimental::RNTupleWriteOptions::fMaxKeySize = kDefaultMaxKeySize

protected

Specifies the max size of a payload storeable into a single TKey.

When writing an RNTuple to a ROOT file, any payload whose size exceeds this will be split into multiple keys.

Definition at line 99 of file RNTupleWriteOptions.hxx.

◆ fMaxUnzippedClusterSize

std::size_t ROOT::Experimental::RNTupleWriteOptions::fMaxUnzippedClusterSize = 10 * fApproxZippedClusterSize

protected

Memory limit for committing a cluster: with very high compression ratio, we need a limit on how large the I/O buffer can grow during writing.

Definition at line 67 of file RNTupleWriteOptions.hxx.

◆ fMaxUnzippedPageSize

std::size_t ROOT::Experimental::RNTupleWriteOptions::fMaxUnzippedPageSize = 1024 * 1024

protected

Pages can grow only to the given limit in bytes.

Definition at line 74 of file RNTupleWriteOptions.hxx.

◆ fPageBufferBudget

std::size_t ROOT::Experimental::RNTupleWriteOptions::fPageBufferBudget = 0

protected

The maximum size that the sum of all page buffers used for writing into a persistent sink are allowed to use.

If set to zero, RNTuple will auto-adjust the budget based on the value of fApproxZippedClusterSize. If set manually, the size needs to be large enough to hold all initial page buffers. The total amount of memory for writing is larger, e.g. for the additional compressed buffers etc. Use RNTupleModel::EstimateWriteMemoryUsage() for the total estimated memory use for writing. The default values are tuned for a total write memory of around 300 MB per fill context.

Definition at line 81 of file RNTupleWriteOptions.hxx.

◆ fUseBufferedWrite

bool ROOT::Experimental::RNTupleWriteOptions::fUseBufferedWrite = true

protected

Whether to use buffered writing (with RPageSinkBuf).

This buffers compressed pages in memory, reorders them to keep pages of the same column adjacent, and coalesces the writes when committing a cluster.

Definition at line 84 of file RNTupleWriteOptions.hxx.

◆ fUseDirectIO

bool ROOT::Experimental::RNTupleWriteOptions::fUseDirectIO = false

protected

Whether to use Direct I/O for writing.

Note that this introduces alignment requirements that may very between filesystems and platforms.

Definition at line 87 of file RNTupleWriteOptions.hxx.

◆ fUseImplicitMT

EImplicitMT ROOT::Experimental::RNTupleWriteOptions::fUseImplicitMT = EImplicitMT::kDefault

protected

Whether to use implicit multi-threading to compress pages. Only has an effect if buffered writing is turned on.

Definition at line 92 of file RNTupleWriteOptions.hxx.

◆ fWriteBufferSize

std::size_t ROOT::Experimental::RNTupleWriteOptions::fWriteBufferSize = 4 * 1024 * 1024

protected

Buffer size to use for writing to files, must be a multiple of 4096 bytes.

Testing suggests that 4MiB gives best performance (with Direct I/O) at a reasonable memory consumption.

Definition at line 90 of file RNTupleWriteOptions.hxx.

◆ kDefaultMaxKeySize

constexpr std::uint64_t ROOT::Experimental::RNTupleWriteOptions::kDefaultMaxKeySize = 0x4000'0000

staticconstexpr

Definition at line 56 of file RNTupleWriteOptions.hxx.

Libraries for ROOT::Experimental::RNTupleWriteOptions:

[legend]

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

tree/ntuple/v7/inc/ROOT/RNTupleWriteOptions.hxx
tree/ntuple/v7/src/RNTupleWriteOptions.cxx

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Member Enumeration Documentation

◆ EImplicitMT

Constructor & Destructor Documentation

◆ ~RNTupleWriteOptions()

Member Function Documentation

◆ Clone()

◆ GetApproxZippedClusterSize()

◆ GetCompression()

◆ GetEnablePageChecksums()

◆ GetEnableSamePageMerging()

◆ GetInitialUnzippedPageSize()

◆ GetMaxKeySize()

◆ GetMaxUnzippedClusterSize()

◆ GetMaxUnzippedPageSize()

◆ GetPageBufferBudget()

◆ GetUseBufferedWrite()

◆ GetUseDirectIO()

◆ GetUseImplicitMT()

◆ GetWriteBufferSize()

◆ SetApproxZippedClusterSize()

◆ SetCompression() [1/2]

◆ SetCompression() [2/2]

◆ SetEnablePageChecksums()

◆ SetEnableSamePageMerging()

◆ SetInitialUnzippedPageSize()

◆ SetMaxUnzippedClusterSize()

◆ SetMaxUnzippedPageSize()

◆ SetPageBufferBudget()

◆ SetUseBufferedWrite()

◆ SetUseDirectIO()

◆ SetUseImplicitMT()

◆ SetWriteBufferSize()

Member Data Documentation

◆ fApproxZippedClusterSize

◆ fCompression

◆ fEnablePageChecksums

◆ fEnableSamePageMerging

◆ fInitialUnzippedPageSize

◆ fMaxKeySize

◆ fMaxUnzippedClusterSize

◆ fMaxUnzippedPageSize

◆ fPageBufferBudget

◆ fUseBufferedWrite

◆ fUseDirectIO

◆ fUseImplicitMT

◆ fWriteBufferSize

◆ kDefaultMaxKeySize