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

int	GetCompression () const

bool	GetEnablePageChecksums () const

std::size_t	GetInitialNElementsPerPage () 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 (int val)

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

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

void	SetInitialNElementsPerPage (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 = 100 * 1000 * 1000
	Approximation of the target compressed cluster size.

int	fCompression {RCompressionSetting::EDefaults::kUseGeneralPurpose}

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

std::size_t	fInitialNElementsPerPage = 64
	Initially, columns start with a page large enough to hold the given number of elements.

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

std::size_t	fMaxUnzippedClusterSize = 1024 * 1024 * 1024
	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 48 of file RNTupleWriteOptions.cxx.

◆ GetApproxZippedClusterSize()

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

inline

Definition at line 112 of file RNTupleWriteOptions.hxx.

◆ GetCompression()

int ROOT::Experimental::RNTupleWriteOptions::GetCompression ( ) const

inline

Definition at line 105 of file RNTupleWriteOptions.hxx.

◆ GetEnablePageChecksums()

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

inline

Definition at line 139 of file RNTupleWriteOptions.hxx.

◆ GetInitialNElementsPerPage()

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

inline

Definition at line 118 of file RNTupleWriteOptions.hxx.

◆ GetMaxKeySize()

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

inline

Definition at line 143 of file RNTupleWriteOptions.hxx.

◆ GetMaxUnzippedClusterSize()

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

inline

Definition at line 115 of file RNTupleWriteOptions.hxx.

◆ GetMaxUnzippedPageSize()

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

inline

Definition at line 121 of file RNTupleWriteOptions.hxx.

◆ GetPageBufferBudget()

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

Definition at line 77 of file RNTupleWriteOptions.cxx.

◆ GetUseBufferedWrite()

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

inline

Definition at line 127 of file RNTupleWriteOptions.hxx.

◆ GetUseDirectIO()

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

inline

Definition at line 130 of file RNTupleWriteOptions.hxx.

◆ GetUseImplicitMT()

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

inline

Definition at line 136 of file RNTupleWriteOptions.hxx.

◆ GetWriteBufferSize()

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

inline

Definition at line 133 of file RNTupleWriteOptions.hxx.

◆ SetApproxZippedClusterSize()

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

Definition at line 53 of file RNTupleWriteOptions.cxx.

◆ SetCompression() [1/2]

void ROOT::Experimental::RNTupleWriteOptions::SetCompression ( int val )

inline

Definition at line 106 of file RNTupleWriteOptions.hxx.

◆ SetCompression() [2/2]

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

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 141 of file RNTupleWriteOptions.hxx.

◆ SetInitialNElementsPerPage()

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

Definition at line 65 of file RNTupleWriteOptions.cxx.

◆ SetMaxUnzippedClusterSize()

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

Definition at line 59 of file RNTupleWriteOptions.cxx.

◆ SetMaxUnzippedPageSize()

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

Definition at line 71 of file RNTupleWriteOptions.cxx.

◆ SetPageBufferBudget()

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

inline

Definition at line 125 of file RNTupleWriteOptions.hxx.

◆ SetUseBufferedWrite()

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

inline

Definition at line 128 of file RNTupleWriteOptions.hxx.

◆ SetUseDirectIO()

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

inline

Definition at line 131 of file RNTupleWriteOptions.hxx.

◆ SetUseImplicitMT()

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

inline

Definition at line 137 of file RNTupleWriteOptions.hxx.

◆ SetWriteBufferSize()

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

inline

Definition at line 134 of file RNTupleWriteOptions.hxx.

Member Data Documentation

◆ fApproxZippedClusterSize

std::size_t ROOT::Experimental::RNTupleWriteOptions::fApproxZippedClusterSize = 100 * 1000 * 1000

protected

Approximation of the target compressed cluster size.

Definition at line 64 of file RNTupleWriteOptions.hxx.

◆ fCompression

int 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 95 of file RNTupleWriteOptions.hxx.

◆ fInitialNElementsPerPage

std::size_t ROOT::Experimental::RNTupleWriteOptions::fInitialNElementsPerPage = 64

protected

Initially, columns start with a page large enough to hold the given number of elements.

The initial page size is the given number of elements multiplied by the column's element size. 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 73 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 98 of file RNTupleWriteOptions.hxx.

◆ fMaxUnzippedClusterSize

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

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 75 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 82 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 85 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 88 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 93 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 91 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()

◆ GetInitialNElementsPerPage()

◆ GetMaxKeySize()

◆ GetMaxUnzippedClusterSize()

◆ GetMaxUnzippedPageSize()

◆ GetPageBufferBudget()

◆ GetUseBufferedWrite()

◆ GetUseDirectIO()

◆ GetUseImplicitMT()

◆ GetWriteBufferSize()

◆ SetApproxZippedClusterSize()

◆ SetCompression() [1/2]

◆ SetCompression() [2/2]

◆ SetEnablePageChecksums()

◆ SetInitialNElementsPerPage()

◆ SetMaxUnzippedClusterSize()

◆ SetMaxUnzippedPageSize()

◆ SetPageBufferBudget()

◆ SetUseBufferedWrite()

◆ SetUseDirectIO()

◆ SetUseImplicitMT()

◆ SetWriteBufferSize()

Member Data Documentation

◆ fApproxZippedClusterSize

◆ fCompression

◆ fEnablePageChecksums

◆ fInitialNElementsPerPage

◆ fMaxKeySize

◆ fMaxUnzippedClusterSize

◆ fMaxUnzippedPageSize

◆ fPageBufferBudget

◆ fUseBufferedWrite

◆ fUseDirectIO

◆ fUseImplicitMT

◆ fWriteBufferSize

◆ kDefaultMaxKeySize