RNTupleReadOptions.hxx

Go to the documentation of this file.

/// \file ROOT/RNTupleReadOptions.hxx
/// \author Jakob Blomer <jblomer@cern.ch>
/// \date 2024-02-22
 
/*************************************************************************
 * Copyright (C) 1995-2024, Rene Brun and Fons Rademakers.               *
 * All rights reserved.                                                  *
 *                                                                       *
 * For the licensing terms see $ROOTSYS/LICENSE.                         *
 * For the list of contributors see $ROOTSYS/README/CREDITS.             *
 *************************************************************************/
 
#ifndef ROOT_RNTupleReadOptions
#define ROOT_RNTupleReadOptions
 
#include <cstdint>
 
namespace ROOT {
 
class RNTupleReadOptions;
 
namespace Internal {
 
class RNTupleReadOptionsManip final {
public:
   static unsigned int GetClusterBunchSize(const RNTupleReadOptions &options);
   static void SetClusterBunchSize(RNTupleReadOptions &options, unsigned int val);
   static unsigned int GetClusterGroupBudget(const RNTupleReadOptions &options);
   static void SetClusterGroupBudget(RNTupleReadOptions &options, unsigned int val);
   static std::uint64_t GetMaxEnvelopeSize(const RNTupleReadOptions &options);
   static void SetMaxEnvelopeSize(RNTupleReadOptions &options, std::uint64_t val);
};
 
} // namespace Internal
 
// clang-format off
/**
\class ROOT::RNTupleReadOptions
\ingroup NTuple
\brief Common user-tunable settings for reading RNTuples
 
All page source classes need to support the common options.
 
<table>
<tr>
<th>Option name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
 
<tr>
<td>`ClusterCache`</td>
<td>EClusterCache</td>
<td>EClusterCache::kDefault</td>
<td>
Controls if the prefetcher (including the prefetcher thread) is used
</td>
</tr>
 
<tr>
<td>`UseImplicitMT`</td>
<td>EImplicitMT</td>
<td>EImplicitMT::kDefault</td>
<td>
Allows to disable parallel page compression and decompression even if ROOT uses implicit MT.
This is useful, e.g., in the context of RDataFrame where the threads are fully managed by RDataFrame.
</td>
</tr>
 
<tr>
<td>`EMetadataMode`</td>
<td>EMetadataMode</td>
<td>EMetadataMode::kDefault</td>
<td>
Set whether cluster metadata (page locations) are loaded entirely on open or on demand during entry iteration.
By default, the RNTuple reader loads metadata on demand.
</td>
</tr>
 
<tr>
<td>`EnableMetrics`</td>
<td>`bool`</td>
<td>`false`</td>
<td>
If `true`, the RNTupleReader will track metrics straight from its construction, as
if calling RNTupleReader::EnableMetrics() before having created the object.
</td>
</tr>
</table>
*/
// clang-format on
class RNTupleReadOptions {
   friend class Internal::RNTupleReadOptionsManip;
 
public:
   enum class EClusterCache {
      kOff,
      kOn,
      kDefault = kOn,
   };
 
   enum class EImplicitMT {
      kOff,
      kDefault,
   };
 
   enum class EMetadataMode {
      kEager,
      kOnDemand,
      kDefault = kOnDemand,
   };
 
private:
   EClusterCache fClusterCache = EClusterCache::kDefault;
   /// The number of cluster to be prefetched in a single batch; this option is transitional and will be replaced
   /// by an option that allows to control the amount of memory that the prefetcher uses.
   unsigned int fClusterBunchSize = 1;
   /// The threshold for the number of concurrently loaded cluster group details as of which the cluster details of the
   /// least recently used cluster groups are evicted. The budget can be overspent due to pinned cluster groups.
   /// Currently a private option that cannot be changed by the user.
   unsigned int fClusterGroupBudget = 2;
   EImplicitMT fUseImplicitMT = EImplicitMT::kDefault;
   EMetadataMode fMetadataMode = EMetadataMode::kDefault;
   bool fEnableMetrics = false;
   /// Largest header or footer envelope a page source will accept from an anchor it does not fully trust,
   /// such as the S3 anchor, which is a separately stored object. Guards the allocation made from those sizes.
   std::uint64_t fMaxEnvelopeSize = 1024 * 1024 * 1024;
 
public:
   EClusterCache GetClusterCache() const { return fClusterCache; }
   void SetClusterCache(EClusterCache val) { fClusterCache = val; }
 
   EImplicitMT GetUseImplicitMT() const { return fUseImplicitMT; }
   void SetUseImplicitMT(EImplicitMT val) { fUseImplicitMT = val; }
 
   EMetadataMode GetMetadataMode() const { return fMetadataMode; }
   void SetMetadataMode(EMetadataMode val) { fMetadataMode = val; }
 
   bool GetEnableMetrics() const { return fEnableMetrics; }
   void SetEnableMetrics(bool val) { fEnableMetrics = val; }
}; // class RNTupleReadOptions
 
namespace Internal {
 
inline unsigned int RNTupleReadOptionsManip::GetClusterBunchSize(const RNTupleReadOptions &options)
{
   return options.fClusterBunchSize;
}
 
inline void RNTupleReadOptionsManip::SetClusterBunchSize(RNTupleReadOptions &options, unsigned int val)
{
   options.fClusterBunchSize = val;
}
 
inline unsigned int RNTupleReadOptionsManip::GetClusterGroupBudget(const RNTupleReadOptions &options)
{
   return options.fClusterGroupBudget;
}
 
inline void RNTupleReadOptionsManip::SetClusterGroupBudget(RNTupleReadOptions &options, unsigned int val)
{
   options.fClusterGroupBudget = val;
}
 
inline std::uint64_t RNTupleReadOptionsManip::GetMaxEnvelopeSize(const RNTupleReadOptions &options)
{
   return options.fMaxEnvelopeSize;
}
 
inline void RNTupleReadOptionsManip::SetMaxEnvelopeSize(RNTupleReadOptions &options, std::uint64_t val)
{
   options.fMaxEnvelopeSize = val;
}
 
} // namespace Internal
} // namespace ROOT
 
#endif