template<typename T>
class ROOT::Detail::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

T	Type of the action result

A wrapper around a shared_ptr which allows to access the result of RDataFrame actions. The underlying object can be accessed by dereferencing the RResultPtr:

ROOT::RDF::RResultPtr<TH1D> histo = rdf.Histo1D(...);

histo->Draw(); // Starts running the event loop

ROOT::RDF::RResultPtr

Smart pointer for the return type of actions.

Definition RResultPtr.hxx:131

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.

When shared ownership to the result is desired, a copy of the underlying shared_ptr can be obtained:

std::shared_ptr<TH1D> ProduceResult(const char *columnname) {
   auto ht = rdf.Histo1D(*h, columname);
   return ht.GetSharedPtr();
}

Note that this will run the event loop. If this is not desired, the RResultPtr can be copied.

Definition at line 131 of file RResultPtr.hxx.

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

Public Member Functions
	RResultPtr ()=default

	RResultPtr (const RResultPtr &)=default

template<typename T2, std::enable_if_t< std::is_constructible< std::shared_ptr< T >, std::shared_ptr< T2 > >::value, int > = 0>
	RResultPtr (const RResultPtr< T2 > &r)
	Convert a RResultPtr<T2> to a RResultPtr<T>.

	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.

RIterationHelper< T >::Iterator_t	end ()
	Return an iterator to the end of the contained object if this makes sense, throw a compilation error otherwise.

T *	GetPtr ()
	Get the pointer to the encapsulated object.

std::shared_ptr< T >	GetSharedPtr ()
	Produce the encapsulated result, and return a shared pointer to it.

const T &	GetValue ()
	Get a const reference to the encapsulated object.

bool	IsReady () const
	Check whether the result has already been computed.

RResultPtr< T > &	OnPartialResult (ULong64_t everyNEvents, std::function< void(T &)> callback)
	Register a callback that RDataFrame will execute "everyNEvents" on a partial result.

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.

	operator bool () const

T &	operator* ()
	Get a reference to the encapsulated object.

T *	operator-> ()
	Get a pointer to the encapsulated object.

RResultPtr &	operator= (const RResultPtr &)=default

RResultPtr &	operator= (RResultPtr &&)=default

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

Private Member Functions
	RResultPtr (std::shared_ptr< T > objPtr, RDFDetail::RLoopManager *lm, std::shared_ptr< RDFInternal::RActionBase > actionPtr)

void	ThrowIfNull ()

void	TriggerRun ()
	Triggers the event loop in the RLoopManager.

Private Attributes
std::shared_ptr< RDFInternal::RActionBase >	fActionPtr
	Owning pointer to the action that will produce this result.

RDFDetail::RLoopManager *	fLoopManager = nullptr
	Non-owning pointer to the RLoopManager at the root of this computation graph.

std::shared_ptr< T >	fObjPtr
	Shared pointer encapsulating the wrapped result.

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)

std::unique_ptr< RDFDetail::RMergeableValue< T > >	RDFDetail::GetMergeableValue (RResultPtr< T > &rptr)

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

ROOT::Internal::RDF::SnapshotPtr_t	ROOT::Internal::RDF::CloneResultAndAction (const ROOT::Internal::RDF::SnapshotPtr_t &inptr, const std::string &outputFileName)

RResultPtr< T >	ROOT::Internal::RDF::CloneResultAndAction (const RResultPtr< T > &inptr)

class	ROOT::Internal::RDF::GraphDrawing::GraphCreatorHelper

template<typename T1>
ROOT::RDF::Experimental::RResultMap< T1 >	ROOT::RDF::Experimental::VariationsFor (RResultPtr< T1 > resPtr)

class	RResultHandle

#include <ROOT/RResultPtr.hxx>

Member Typedef Documentation

◆ Value_t

template<typename T>

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

Convenience alias to simplify access to proxied type.

Definition at line 205 of file RResultPtr.hxx.

Constructor & Destructor Documentation

◆ RResultPtr() [1/5]

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 198 of file RResultPtr.hxx.

◆ RResultPtr() [2/5]

template<typename T>

ROOT::RDF::RResultPtr< T >::RResultPtr ( )

default

◆ RResultPtr() [3/5]

template<typename T>

ROOT::RDF::RResultPtr< T >::RResultPtr ( const RResultPtr< T > & )

default

◆ RResultPtr() [4/5]

template<typename T>

ROOT::RDF::RResultPtr< T >::RResultPtr ( RResultPtr< T > && )

default

◆ RResultPtr() [5/5]

template<typename T>

template<typename T2, std::enable_if_t< std::is_constructible< std::shared_ptr< T >, std::shared_ptr< T2 > >::value, int > = 0>

ROOT::RDF::RResultPtr< T >::RResultPtr ( const RResultPtr< T2 > & r )

inline

Convert a RResultPtr<T2> to a RResultPtr<T>.

Useful e.g. to store a number of RResultPtr<TH1D> and RResultPtr<TH2D> in a std::vector<RResultPtr<TH1>>. The requirements on T2 and T are the same as for conversion between std::shared_ptr<T2> and std::shared_ptr<T>.

Definition at line 221 of file RResultPtr.hxx.

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 268 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 278 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.

Note: Ownership is not transferred to the caller.

Definition at line 247 of file RResultPtr.hxx.

◆ GetSharedPtr()

template<typename T>

std::shared_ptr< T > ROOT::RDF::RResultPtr< T >::GetSharedPtr ( )

inline

Produce the encapsulated result, and return a shared pointer to it.

If RDataFrame hasn't produced the result yet, triggers the event loop and execution of all actions booked in the associated RLoopManager.

Note: To share a "lazy" handle to the result without running the event loop, copy the RResultPtr.

Definition at line 229 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 238 of file RResultPtr.hxx.

◆ IsReady()

template<typename T>

bool ROOT::RDF::RResultPtr< T >::IsReady ( ) const

inline

Check whether the result has already been computed.

auto res = df.Count();
res.IsReady(); // false, access will trigger event loop
std::cout << *res << std::endl; // triggers event loop
res.IsReady(); // true

Definition at line 407 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]	everyNEvents	Frequency at which the callback will be called, as a number of events processed
[in]	callback	a 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 be executed by the first worker that arrives at the callback, and then only be executed when the same result is updated. For example, if dataframe uses N internal copies of a result, it will always be the ith < N object that is passed into the callback.
will always be executed "everyNEvents": the partial result passed into the callback will have accumulated N more events, irrespective of the progress that other worker threads make.
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 332 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]	everyNEvents	Frequency at which the callback will be called by each thread, as a number of events processed
[in]	callback	A callable 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 385 of file RResultPtr.hxx.

◆ operator bool()

template<typename T>

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

inlineexplicit

Definition at line 213 of file RResultPtr.hxx.

◆ operator*()

template<typename T>

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

inline

Get a reference to the encapsulated object.

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

Definition at line 251 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.

Note: Ownership is not transferred to the caller.

Definition at line 260 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

◆ ThrowIfNull()

template<typename T>

void ROOT::RDF::RResultPtr< T >::ThrowIfNull ( )

inlineprivate

Definition at line 192 of file RResultPtr.hxx.

◆ TriggerRun()

template<typename T>

void ROOT::RDF::RResultPtr< T >::TriggerRun ( )

private

Triggers the event loop in the RLoopManager.

Definition at line 416 of file RResultPtr.hxx.

Friends And Related Symbol Documentation

◆ RResultPtr

template<typename T>

template<typename T1>

friend class RResultPtr

friend

Definition at line 134 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 428 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 446 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 452 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 422 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 434 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 440 of file RResultPtr.hxx.

◆ RDFDetail::GetMergeableValue

template<typename T>

std::unique_ptr< RDFDetail::RMergeableValue< T > > RDFDetail::GetMergeableValue ( RResultPtr< T > & rptr )

friend

◆ 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::CloneResultAndAction [1/2]

template<typename T>

ROOT::Internal::RDF::SnapshotPtr_t ROOT::Internal::RDF::CloneResultAndAction	(	const ROOT::Internal::RDF::SnapshotPtr_t &	inptr,
		const std::string &	outputFileName )

friend

◆ ROOT::Internal::RDF::CloneResultAndAction [2/2]

template<typename T>

RResultPtr< T > ROOT::Internal::RDF::CloneResultAndAction ( const RResultPtr< T > & inptr )

friend

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

template<typename T>

friend class ROOT::Internal::RDF::GraphDrawing::GraphCreatorHelper

friend

Definition at line 157 of file RResultPtr.hxx.

◆ ROOT::RDF::Experimental::VariationsFor

template<typename T>

template<typename T1>

ROOT::RDF::Experimental::RResultMap< T1 > ROOT::RDF::Experimental::VariationsFor ( RResultPtr< T1 > resPtr )

friend

◆ RResultHandle

template<typename T>

friend class RResultHandle

friend

Definition at line 159 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 187 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 183 of file RResultPtr.hxx.

◆ fObjPtr

template<typename T>

std::shared_ptr<T> ROOT::RDF::RResultPtr< T >::fObjPtr

private

Shared pointer encapsulating the wrapped result.

Definition at line 184 of file RResultPtr.hxx.

◆ kOnce

template<typename T>

ULong64_t ROOT::RDF::RResultPtr< T >::kOnce = 0ull

staticconstexpr

Convenience definition to express a callback must be executed once.

Definition at line 206 of file RResultPtr.hxx.

tree/dataframe/inc/ROOT/RResultPtr.hxx

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Friends

Member Typedef Documentation

◆ Value_t

Constructor & Destructor Documentation

◆ RResultPtr() [1/5]

◆ RResultPtr() [2/5]

◆ RResultPtr() [3/5]

◆ RResultPtr() [4/5]

◆ RResultPtr() [5/5]

Member Function Documentation

◆ begin()

◆ end()

◆ GetPtr()

◆ GetSharedPtr()

◆ GetValue()

◆ IsReady()

◆ OnPartialResult()

◆ OnPartialResultSlot()

◆ operator bool()

◆ operator*()

◆ operator->()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ThrowIfNull()

◆ TriggerRun()

Friends And Related Symbol Documentation

◆ RResultPtr

◆ operator!= [1/3]

◆ operator!= [2/3]

◆ operator!= [3/3]

◆ operator== [1/3]

◆ operator== [2/3]

◆ operator== [3/3]

◆ RDFDetail::GetMergeableValue

◆ RDFDetail::MakeResultPtr

◆ ROOT::Internal::RDF::CloneResultAndAction [1/2]

◆ ROOT::Internal::RDF::CloneResultAndAction [2/2]

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

◆ ROOT::RDF::Experimental::VariationsFor

◆ RResultHandle

Member Data Documentation

◆ fActionPtr

◆ fLoopManager

◆ fObjPtr

◆ kOnce