Logo ROOT   6.19/01
Reference Guide
ROOT::RDF::RResultPtr< T > Class Template Reference

template<typename T>
class ROOT::RDF::RResultPtr< T >

Smart pointer for the return type of actions.

A wrapper around the result of RDataFrame actions able to trigger calculations lazily.

Template Parameters
TType of the action result

A smart pointer which allows to access the result of a RDataFrame action. The methods of the encapsulated object can be accessed via the arrow operator. Upon invocation of the arrow operator or dereferencing (operator*), the loop on the events and calculations of all scheduled actions are executed if needed. It is possible to iterate on the result proxy if the proxied object is a collection.

for (auto& myItem : myResultProxy) { ... };

If iteration is not supported by the type of the proxied object, a compilation error is thrown.

Definition at line 50 of file InterfaceUtils.hxx.

Public Types

using Value_t = T
 Convenience alias to simplify access to proxied type. More...
 

Public Member Functions

 RResultPtr ()=default
 
 RResultPtr (const RResultPtr &)=default
 
 RResultPtr (RResultPtr &&)=default
 
RIterationHelper< T >::Iterator_t begin ()
 Return an iterator to the beginning of the contained object if this makes sense, throw a compilation error otherwise. More...
 
RIterationHelper< T >::Iterator_t end ()
 Return an iterator to the end of the contained object if this makes sense, throw a compilation error otherwise. More...
 
T * GetPtr ()
 Get the pointer to the encapsulated object. More...
 
const T & GetValue ()
 Get a const reference to the encapsulated object. More...
 
RResultPtr< T > & OnPartialResult (ULong64_t everyNEvents, std::function< void(T &)> callback)
 Register a callback that RDataFrame will execute "everyNEvents" on a partial result. More...
 
RResultPtr< T > & OnPartialResultSlot (ULong64_t everyNEvents, std::function< void(unsigned int, T &)> callback)
 Register a callback that RDataFrame will execute in each worker thread concurrently on that thread's partial result. More...
 
 operator bool () const
 
template<typename TO , typename std::enable_if< std::is_convertible< T, TO >::value, int >::type = 0>
 operator RResultPtr< TO > () const
 
T & operator* ()
 Get a pointer to the encapsulated object. More...
 
T * operator-> ()
 Get a pointer to the encapsulated object. More...
 
RResultPtroperator= (const RResultPtr &)=default
 
RResultPtroperator= (RResultPtr &&)=default
 

Static Public Attributes

static constexpr ULong64_t kOnce = 0ull
 Convenience definition to express a callback must be executed once. More...
 

Private Types

using SPT_t = std::shared_ptr< T >
 

Private Member Functions

 RResultPtr (std::shared_ptr< T > objPtr, RDFDetail::RLoopManager *lm, std::shared_ptr< RDFInternal::RActionBase > actionPtr)
 
T * Get ()
 Get the pointer to the encapsulated result. More...
 
void TriggerRun ()
 Triggers the event loop in the RLoopManager. More...
 

Private Attributes

std::shared_ptr< RDFInternal::RActionBasefActionPtr
 Owning pointer to the action that will produce this result. More...
 
RDFDetail::RLoopManagerfLoopManager = nullptr
 Non-owning pointer to the RLoopManager at the root of this computation graph. More...
 
SPT_t fObjPtr
 Shared pointer encapsulating the wrapped result. More...
 

Friends

template<typename T1 >
class RResultPtr
 
template<class T1 , class T2 >
bool operator!= (const RResultPtr< T1 > &lhs, const RResultPtr< T2 > &rhs)
 
template<class T1 >
bool operator!= (const RResultPtr< T1 > &lhs, std::nullptr_t rhs)
 
template<class T1 >
bool operator!= (std::nullptr_t lhs, const RResultPtr< T1 > &rhs)
 
template<class T1 , class T2 >
bool operator== (const RResultPtr< T1 > &lhs, const RResultPtr< T2 > &rhs)
 
template<class T1 >
bool operator== (const RResultPtr< T1 > &lhs, std::nullptr_t rhs)
 
template<class T1 >
bool operator== (std::nullptr_t lhs, const RResultPtr< T1 > &rhs)
 
template<typename T1 >
RResultPtr< T1RDFDetail::MakeResultPtr (const std::shared_ptr< T1 > &, ::ROOT::Detail::RDF::RLoopManager &, std::shared_ptr< RDFInternal::RActionBase >)
 
class ROOT::Internal::RDF::GraphDrawing::GraphCreatorHelper
 

#include <ROOT/RDF/InterfaceUtils.hxx>

Member Typedef Documentation

◆ SPT_t

template<typename T>
using ROOT::RDF::RResultPtr< T >::SPT_t = std::shared_ptr<T>
private

Definition at line 74 of file RResultPtr.hxx.

◆ Value_t

template<typename T>
using ROOT::RDF::RResultPtr< T >::Value_t = T

Convenience alias to simplify access to proxied type.

Definition at line 142 of file RResultPtr.hxx.

Constructor & Destructor Documentation

◆ RResultPtr() [1/4]

template<typename T>
ROOT::RDF::RResultPtr< T >::RResultPtr ( std::shared_ptr< T >  objPtr,
RDFDetail::RLoopManager lm,
std::shared_ptr< RDFInternal::RActionBase actionPtr 
)
inlineprivate

Definition at line 135 of file RResultPtr.hxx.

◆ RResultPtr() [2/4]

template<typename T>
ROOT::RDF::RResultPtr< T >::RResultPtr ( )
default

◆ RResultPtr() [3/4]

template<typename T>
ROOT::RDF::RResultPtr< T >::RResultPtr ( const RResultPtr< T > &  )
default

◆ RResultPtr() [4/4]

template<typename T>
ROOT::RDF::RResultPtr< T >::RResultPtr ( RResultPtr< T > &&  )
default

Member Function Documentation

◆ begin()

template<typename T>
RIterationHelper<T>::Iterator_t ROOT::RDF::RResultPtr< T >::begin ( )
inline

Return an iterator to the beginning of the contained object if this makes sense, throw a compilation error otherwise.

Definition at line 180 of file RResultPtr.hxx.

◆ end()

template<typename T>
RIterationHelper<T>::Iterator_t ROOT::RDF::RResultPtr< T >::end ( )
inline

Return an iterator to the end of the contained object if this makes sense, throw a compilation error otherwise.

Definition at line 189 of file RResultPtr.hxx.

◆ Get()

template<typename T>
T* ROOT::RDF::RResultPtr< T >::Get ( )
inlineprivate

Get the pointer to the encapsulated result.

Ownership is not transferred to the caller. Triggers event loop and execution of all actions booked in the associated RLoopManager.

Definition at line 128 of file RResultPtr.hxx.

◆ GetPtr()

template<typename T>
T* ROOT::RDF::RResultPtr< T >::GetPtr ( )
inline

Get the pointer to the encapsulated object.

Triggers event loop and execution of all actions booked in the associated RLoopManager.

Definition at line 167 of file RResultPtr.hxx.

◆ GetValue()

template<typename T>
const T& ROOT::RDF::RResultPtr< T >::GetValue ( )
inline

Get a const reference to the encapsulated object.

Triggers event loop and execution of all actions booked in the associated RLoopManager.

Definition at line 163 of file RResultPtr.hxx.

◆ OnPartialResult()

template<typename T>
RResultPtr<T>& ROOT::RDF::RResultPtr< T >::OnPartialResult ( ULong64_t  everyNEvents,
std::function< void(T &)>  callback 
)
inline

Register a callback that RDataFrame will execute "everyNEvents" on a partial result.

Parameters
[in]everyNEventsFrequency at which the callback will be called, as a number of events processed
[in]callbacka callable with signature void(Value_t&) where Value_t is the type of the value contained in this RResultPtr
Returns
this RResultPtr, to allow chaining of OnPartialResultSlot with other calls

The callback must be a callable (lambda, function, functor class...) that takes a reference to the result type as argument and returns nothing. RDataFrame will invoke registered callbacks passing partial action results as arguments to them (e.g. a histogram filled with a part of the selected events, a counter incremented only up to a certain point, a mean over a subset of the events and so forth).

Callbacks can be used e.g. to inspect partial results of the analysis while the event loop is running. For example one can draw an up-to-date version of a result histogram every 100 entries like this:

auto h = tdf.Histo1D("x");
TCanvas c("c","x hist");
h.OnPartialResult(100, [&c](TH1D &h_) { c.cd(); h_.Draw(); c.Update(); });
h->Draw(); // event loop runs here, this `Draw` is executed after the event loop is finished

A value of 0 for everyNEvents indicates the callback must be executed only once, before running the event loop. A conveniece definition kOnce is provided to make this fact more expressive in user code (see snippet below). Multiple callbacks can be registered with the same RResultPtr (i.e. results of RDataFrame actions) and will be executed sequentially. Callbacks are executed in the order they were registered. The type of the value contained in a RResultPtr is also available as RResultPtr<T>::Value_t, e.g.

auto h = tdf.Histo1D("x");
// h.kOnce is 0
// decltype(h)::Value_t is TH1D

When implicit multi-threading is enabled, the callback:

  • will never be executed by multiple threads concurrently: it needs not be thread-safe. For example the snippet above that draws the partial histogram on a canvas works seamlessly in multi-thread event loops.
  • will always be executed "everyNEvents": partial results will "contain" that number of events more from one call to the next
  • might be executed by a different worker thread at different times: the value of std::this_thread::get_id() might change between calls

To register a callback that is called by each worker thread (concurrently) every N events one can use OnPartialResultSlot().

Definition at line 239 of file RResultPtr.hxx.

◆ OnPartialResultSlot()

template<typename T>
RResultPtr<T>& ROOT::RDF::RResultPtr< T >::OnPartialResultSlot ( ULong64_t  everyNEvents,
std::function< void(unsigned int, T &)>  callback 
)
inline

Register a callback that RDataFrame will execute in each worker thread concurrently on that thread's partial result.

Parameters
[in]everyNEventsFrequency at which the callback will be called by each thread, as a number of events processed
[in]acallable with signature void(unsigned int, Value_t&) where Value_t is the type of the value contained in this RResultPtr
Returns
this RResultPtr, to allow chaining of OnPartialResultSlot with other calls

See OnPartialResult for a generic explanation of the callback mechanism. Compared to OnPartialResult, this method has two major differences:

  • all worker threads invoke the callback once every specified number of events. The event count is per-thread, and callback invocation might happen concurrently (i.e. the callback must be thread-safe)
  • the callable must take an extra unsigned int parameter corresponding to a multi-thread "processing slot": this is a "helper value" to simplify writing thread-safe callbacks: different worker threads might invoke the callback concurrently but always with different slot numbers.
  • a value of 0 for everyNEvents indicates the callback must be executed once per slot.

For example, the following snippet prints out a thread-safe progress bar of the events processed by RDataFrame

auto c = tdf.Count(); // any action would do, but `Count` is the most lightweight
std::string progress;
std::mutex bar_mutex;
c.OnPartialResultSlot(nEvents / 100, [&progress, &bar_mutex](unsigned int, ULong64_t &) {
std::lock_guard<std::mutex> lg(bar_mutex);
progress.push_back('#');
std::cout << "\r[" << std::left << std::setw(100) << progress << ']' << std::flush;
});
std::cout << "Analysis running..." << std::endl;
*c; // trigger the event loop by accessing an action's result
std::cout << "\nDone!" << std::endl;

Definition at line 284 of file RResultPtr.hxx.

◆ operator bool()

template<typename T>
ROOT::RDF::RResultPtr< T >::operator bool ( ) const
inlineexplicit

Definition at line 150 of file RResultPtr.hxx.

◆ operator RResultPtr< TO >()

template<typename T>
template<typename TO , typename std::enable_if< std::is_convertible< T, TO >::value, int >::type = 0>
ROOT::RDF::RResultPtr< T >::operator RResultPtr< TO > ( ) const
inline

Definition at line 152 of file RResultPtr.hxx.

◆ operator*()

template<typename T>
T& ROOT::RDF::RResultPtr< T >::operator* ( )
inline

Get a pointer to the encapsulated object.

Triggers event loop and execution of all actions booked in the associated RLoopManager.

Definition at line 171 of file RResultPtr.hxx.

◆ operator->()

template<typename T>
T* ROOT::RDF::RResultPtr< T >::operator-> ( )
inline

Get a pointer to the encapsulated object.

Ownership is not transferred to the caller. Triggers event loop and execution of all actions booked in the associated RLoopManager.

Definition at line 176 of file RResultPtr.hxx.

◆ operator=() [1/2]

template<typename T>
RResultPtr& ROOT::RDF::RResultPtr< T >::operator= ( const RResultPtr< T > &  )
default

◆ operator=() [2/2]

template<typename T>
RResultPtr& ROOT::RDF::RResultPtr< T >::operator= ( RResultPtr< T > &&  )
default

◆ TriggerRun()

template<typename T >
void ROOT::RDF::RResultPtr< T >::TriggerRun ( )
private

Triggers the event loop in the RLoopManager.

Definition at line 297 of file RResultPtr.hxx.

Friends And Related Function Documentation

◆ RResultPtr

template<typename T>
template<typename T1 >
friend class RResultPtr
friend

Definition at line 78 of file RResultPtr.hxx.

◆ operator!= [1/3]

template<typename T>
template<class T1 , class T2 >
bool operator!= ( const RResultPtr< T1 > &  lhs,
const RResultPtr< T2 > &  rhs 
)
friend

Definition at line 309 of file RResultPtr.hxx.

◆ operator!= [2/3]

template<typename T>
template<class T1 >
bool operator!= ( const RResultPtr< T1 > &  lhs,
std::nullptr_t  rhs 
)
friend

Definition at line 327 of file RResultPtr.hxx.

◆ operator!= [3/3]

template<typename T>
template<class T1 >
bool operator!= ( std::nullptr_t  lhs,
const RResultPtr< T1 > &  rhs 
)
friend

Definition at line 333 of file RResultPtr.hxx.

◆ operator== [1/3]

template<typename T>
template<class T1 , class T2 >
bool operator== ( const RResultPtr< T1 > &  lhs,
const RResultPtr< T2 > &  rhs 
)
friend

Definition at line 303 of file RResultPtr.hxx.

◆ operator== [2/3]

template<typename T>
template<class T1 >
bool operator== ( const RResultPtr< T1 > &  lhs,
std::nullptr_t  rhs 
)
friend

Definition at line 315 of file RResultPtr.hxx.

◆ operator== [3/3]

template<typename T>
template<class T1 >
bool operator== ( std::nullptr_t  lhs,
const RResultPtr< T1 > &  rhs 
)
friend

Definition at line 321 of file RResultPtr.hxx.

◆ RDFDetail::MakeResultPtr

template<typename T>
template<typename T1 >
RResultPtr<T1> RDFDetail::MakeResultPtr ( const std::shared_ptr< T1 > &  ,
::ROOT::Detail::RDF::RLoopManager ,
std::shared_ptr< RDFInternal::RActionBase  
)
friend

◆ ROOT::Internal::RDF::GraphDrawing::GraphCreatorHelper

template<typename T>
friend class ROOT::Internal::RDF::GraphDrawing::GraphCreatorHelper
friend

Definition at line 96 of file RResultPtr.hxx.

Member Data Documentation

◆ fActionPtr

template<typename T>
std::shared_ptr<RDFInternal::RActionBase> ROOT::RDF::RResultPtr< T >::fActionPtr
private

Owning pointer to the action that will produce this result.

Ownership is shared with other copies of this ResultPtr.

Definition at line 120 of file RResultPtr.hxx.

◆ fLoopManager

template<typename T>
RDFDetail::RLoopManager* ROOT::RDF::RResultPtr< T >::fLoopManager = nullptr
private

Non-owning pointer to the RLoopManager at the root of this computation graph.

The RLoopManager is guaranteed to be always in scope if fLoopManager is not a nullptr.

Definition at line 116 of file RResultPtr.hxx.

◆ fObjPtr

template<typename T>
SPT_t ROOT::RDF::RResultPtr< T >::fObjPtr
private

Shared pointer encapsulating the wrapped result.

Definition at line 117 of file RResultPtr.hxx.

◆ kOnce

template<typename T>
constexpr ULong64_t ROOT::RDF::RResultPtr< T >::kOnce = 0ull
static

Convenience definition to express a callback must be executed once.

Definition at line 143 of file RResultPtr.hxx.


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