root/ROOT/RNTupleWriteOptions.hxx

0001 /// \file ROOT/RNTupleWriteOptions.hxx
0002 /// \ingroup NTuple ROOT7
0003 /// \author Jakob Blomer <jblomer@cern.ch>
0004 /// \date 2024-02-22
0005 /// \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback
0006 /// is welcome!
0007
0008 /*************************************************************************
0009  * Copyright (C) 1995-2019, Rene Brun and Fons Rademakers.               *
0010  * All rights reserved.                                                  *
0011  *                                                                       *
0012  * For the licensing terms see $ROOTSYS/LICENSE.                         *
0013  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
0014  *************************************************************************/
0015
0016 #ifndef ROOT7_RNTupleWriteOptions
0017 #define ROOT7_RNTupleWriteOptions
0018
0019 #include <Compression.h>
0020
0021 #include <cstdint>
0022 #include <cstddef>
0023 #include <memory>
0024
0025 namespace ROOT {
0026 namespace Experimental {
0027
0028 // clang-format off
0029 /**
0030 \class ROOT::Experimental::RNTupleWriteOptions
0031 \ingroup NTuple
0032 \brief Common user-tunable settings for storing ntuples
0033
0034 All page sink classes need to support the common options.
0035 */
0036 // clang-format on
0037 class RNTupleWriteOptions {
0038 public:
0039    enum class EImplicitMT {
0040       kOff,
0041       kDefault,
0042    };
0043
0044 protected:
0045    int fCompression{RCompressionSetting::EDefaults::kUseGeneralPurpose};
0046    /// Approximation of the target compressed cluster size
0047    std::size_t fApproxZippedClusterSize = 50 * 1000 * 1000;
0048    /// Memory limit for committing a cluster: with very high compression ratio, we need a limit
0049    /// on how large the I/O buffer can grow during writing.
0050    std::size_t fMaxUnzippedClusterSize = 512 * 1024 * 1024;
0051    /// Should be just large enough so that the compression ratio does not benefit much more from larger pages.
0052    /// Unless the cluster is too small to contain a sufficiently large page, pages are
0053    /// fApproxUnzippedPageSize in size and tail pages (the last page in a cluster) is between
0054    /// fApproxUnzippedPageSize/2 and fApproxUnzippedPageSize * 1.5 in size.
0055    std::size_t fApproxUnzippedPageSize = 64 * 1024;
0056    bool fUseBufferedWrite = true;
0057    EImplicitMT fUseImplicitMT = EImplicitMT::kDefault;
0058    /// If set, 64bit index columns are replaced by 32bit index columns. This limits the cluster size to 512MB
0059    /// but it can result in smaller file sizes for data sets with many collections and lz4 or no compression.
0060    bool fHasSmallClusters = false;
0061
0062 public:
0063    /// A maximum size of 512MB still allows for a vector of bool to be stored in a small cluster.  This is the
0064    /// worst case wrt. the maximum required size of the index column.  A 32bit index column can address 512MB
0065    /// of 1-bit (on disk size) bools.
0066    static constexpr std::uint64_t kMaxSmallClusterSize = 512 * 1024 * 1024;
0067
0068    virtual ~RNTupleWriteOptions() = default;
0069    virtual std::unique_ptr<RNTupleWriteOptions> Clone() const;
0070
0071    int GetCompression() const { return fCompression; }
0072    void SetCompression(int val) { fCompression = val; }
0073    void SetCompression(RCompressionSetting::EAlgorithm::EValues algorithm, int compressionLevel)
0074    {
0075       fCompression = CompressionSettings(algorithm, compressionLevel);
0076    }
0077
0078    std::size_t GetApproxZippedClusterSize() const { return fApproxZippedClusterSize; }
0079    void SetApproxZippedClusterSize(std::size_t val);
0080
0081    std::size_t GetMaxUnzippedClusterSize() const { return fMaxUnzippedClusterSize; }
0082    void SetMaxUnzippedClusterSize(std::size_t val);
0083
0084    std::size_t GetApproxUnzippedPageSize() const { return fApproxUnzippedPageSize; }
0085    void SetApproxUnzippedPageSize(std::size_t val);
0086
0087    bool GetUseBufferedWrite() const { return fUseBufferedWrite; }
0088    void SetUseBufferedWrite(bool val) { fUseBufferedWrite = val; }
0089
0090    EImplicitMT GetUseImplicitMT() const { return fUseImplicitMT; }
0091    void SetUseImplicitMT(EImplicitMT val) { fUseImplicitMT = val; }
0092
0093    bool GetHasSmallClusters() const { return fHasSmallClusters; }
0094    void SetHasSmallClusters(bool val) { fHasSmallClusters = val; }
0095 };
0096
0097 } // namespace Experimental
0098 } // namespace ROOT
0099
0100 #endif // ROOT7_RNTupleWriteOptions