util::ArtHandleTrackerManager< Event > Class Template Reference

Manages handle trackers for an easy call of removeCachedProduct(). More...

#include <ArtHandleTrackerManager.h>

Classes
struct	Config_t
	Configuration record. More...

Public Types
using	Event_t = Event
	Type of data viewer object to operate with. More...

Public Member Functions
	ArtHandleTrackerManager (Config_t config={})
	Constructs a handle manager. More...
	ArtHandleTrackerManager (Event_t const &event, Config_t config={})
	Constructs a handle manager covering event. More...
template<typename Handle >
auto	registerHandle (Handle &&handle) -> decltype(auto)
Queries
unsigned int	nTrackedHandles () const
	Returns the number of handles currently tracked. More...
bool	hasEvent () const
	Returns whether the object is associated to an event. More...
Registration of data products
template<typename T , typename... Args>
art::Handle< T >	getHandle (Args &&...args)
	Retrieves an handle from the event, and registers it. More...
template<typename T , typename... Args>
art::ValidHandle< T >	getValidHandle (Args &&...args)
	Retrieves a valid handle from the event, and registers it. More...
template<typename Handle >
decltype(auto)	registerHandle (Handle &&handle)
	Registers an existing handle. More...
Operations
void	useEvent (Event_t const &event)
	Changes the event being served. More...
unsigned int	removeCachedProducts ()
	Clears the cached data products for all tracked handles. More...
void	forgetAllHandles ()
	Stops tracking any handle, without removing their cache first. More...
unsigned int	doneWithEvent (bool removeCache=true, art::Event const *event=nullptr)
	Completes the work on the associated event. More...

Private Types
using	TrackerPtr = std::unique_ptr< util::ArtHandleTrackerInterface< Event_t >>
	Type of pointer to any handle tracker. More...

Private Member Functions
template<typename Handle >
Handle const *	findHandle (Handle const &like) const
	Returns the pointer to an handle equivalent to like. More...
void	canOperate (const char *where) const

Static Private Member Functions
template<typename Handle >
static bool	handleSameProduct (TrackerPtr tracker, Handle const &handle)
	Returns whether tracker tracks the same product that handle handles. More...

Private Attributes
Event_t const *	fEvent = nullptr
	Event being manager. Must be present! More...
Config_t const	fConfig
	Configuration. More...
std::vector< TrackerPtr >	fTrackers
	List of managed handle trackers. More...

Detailed Description

template<typename Event>
class util::ArtHandleTrackerManager< Event >

Manages handle trackers for an easy call of removeCachedProduct().

Template Parameters

Event

the type of data product source (the "principal") to serve

This handle manager is designed to simplify the usage of art::Event::removeCachedProduct() on multiple data products.

The envisioned usage model in a single-thread module is the following:

1. The manager is a data member of the module (in alternative, it should be passed down to the places where data products are read, and at a minimum it needs to register all the handles it is supposed to "manage").
2. The manager can ask the event to read a data product anew, and get an handle for it. It will register the handle, and return it.
   • The manager can also register an existing handle.
3. The manager can deliver a stored handle (but that's a slow process in the current implementation and it requires the input tag to resolve ambiguities).
4. Upon request, all handles are asked to remove their cached products. This request presumably happens at the end of the event-processing function (produce(), filter(), analyze()). Note that after an handle has its cached data removed, it's clear()'ed.

An handle manager can serve only one art event at a time. All handles come from that event (or are assumed to).

Example:

class MyModule: public art::EDAnalyzer {

  util::ArtHandleTrackerManager<art::Event> fDataCacheRemover;

  art::InputTag const fTag;

  // ...

  void analyze(art::Event const & event) override
    {
      fDataCacheRemover.useEvent(event);

      auto const& handle = fDataCacheRemover.getHandle<MyDataProduct>(fTag);

      auto results = processData(*handle); // ... or whatever

      fDataCacheRemover.removeCachedProducts(); // free caches after use

      results.Write(); // ... or another portion of whatever
    }

};

Or one can create the handle as preferred, and then register it:

class MyModule: public art::EDAnalyzer {

  util::ArtHandleTrackerManager<art::Event> fDataCacheRemover;

  art::InputTag const fTag;

  // ...

  void analyze(art::Event const & event) override
    {
      fDataCacheRemover.useEvent(event);

      auto const& handle = event.getValidHandle<MyDataProduct>(fTag);

      fDataCacheRemover.registerHandle(handle);

      auto results = processData(*handle); // ... or whatever

      fDataCacheRemover.removeCachedProducts(); // free caches after use

      results.Write(); // ... or another portion of whatever
    }

};

Technical notes

Support for different types of handles

Currently, both art::Handle and art::ValidHandle (and nothing else) can be created by ArtHandleTrackerManager. The code can be extended to support any object that can be passed to art::Event::removeCachedProduct() (e.g. art::ProductID, if it will ever happen).

The current implementation is expected to be able to recognize handles pointing to the same data product even if they are of different type (e.g. art::Handle<T> and art::ValidHandle<T>). The manager stores a copy of the first type of handle registered for a given data product; then, if another handle of any type to the same data product is requested or registered, registerHandle() will return the same handle in argument, and the getHandle() family of functions will get and return a new handle. In both cases, no new registration will happen.

Multithreading

The current implementation is inherently not safe for art multithreading. While the inner data structure don't need global state, and the interface can easily be extended to allow for no global state as well, the operations are still performed on all the registered handles at once (meaning, when one thread asks for removeCachedProduct() or forgetAllHandles(), data from all events is affected). This can be overcome by changing the internal storage (to be reentrant and possibly by event) and a bit of the interface.

The object as it is now can be implemented on top of such object, preserving the current event information and delivering it to the new manager under the hood, with minimal overhead.

If such feature is needed, ask the author (and be prepared to test it).

Definition at line 32 of file ArtHandleTrackerManager.h.

Member Typedef Documentation

template<typename Event>

using util::ArtHandleTrackerManager< Event >::Event_t = Event

Type of data viewer object to operate with.

Definition at line 163 of file ArtHandleTrackerManager.h.

template<typename Event>

using util::ArtHandleTrackerManager< Event >::TrackerPtr = std::unique_ptr<util::ArtHandleTrackerInterface<Event_t>>

private

Type of pointer to any handle tracker.

Definition at line 322 of file ArtHandleTrackerManager.h.

Constructor & Destructor Documentation

template<typename Event >

util::ArtHandleTrackerManager< Event >::ArtHandleTrackerManager

(

Config_t

config = {}

)

Constructs a handle manager.

Parameters

config

(optional) the configuration to be used

See Also

useEvent()

An event must be later assigned to it (useEvent()) to make it functional.

Definition at line 783 of file ArtHandleTrackerManager.h.

  : fConfig{ std::move(config) }
{}

template<typename Event >

util::ArtHandleTrackerManager< Event >::ArtHandleTrackerManager	(	Event_t const &	event,
		Config_t	config = {}
	)

Constructs a handle manager covering event.

Parameters

event

the first data viewer (event) object to operate on

Definition at line 791 of file ArtHandleTrackerManager.h.

  : fEvent{ &event }, fConfig{ std::move(config) }
{}

Member Function Documentation

template<typename Event >

void util::ArtHandleTrackerManager< Event >::canOperate ( const char *  where ) const

private

Checks that the object is in a state where it can perform operations.

Parameters

where

identification of the calling function for error messages

Exceptions

art::Exception

(code: art::errors::LogicError) on failure

Definition at line 981 of file ArtHandleTrackerManager.h.

                                                                           {
  
  if (fEvent) return;
  
  throw art::Exception(art::errors::LogicError)
    << "util::ArtHandleTrackerManager attempted an operation without a valid"
      " event.\nThe operation was: " << where << "\n";
  
} // util::ArtHandleTrackerManager<Event>::canOperate()

template<typename Event>

unsigned int util::ArtHandleTrackerManager< Event >::doneWithEvent	(	bool	removeCache = true,
		art::Event const *	event = nullptr
	)

Completes the work on the associated event.

Parameters

removeCache	(default: true) removes tracked data product caches
event	if specified, only acts on cache from this event

Returns

the number of cleared data product caches

This is a shortcut for having optional release of cache in a single call, depending on the value of removeCache:

• if true, removeCachedProducts() is called and its count is returned;
• if false, forgetAllHandles() is called and 0 is returned.

In addition, the object is disassociated from the event, and a call to useEvent() will be needed before this object can be operative again.

If the event parameter is not null, a check is done that the event being currently used matches event, and if not no operation happens (0 is returned, but the object is not disassociated from its current event).

Definition at line 920 of file ArtHandleTrackerManager.h.

{
  if (event && (fEvent != event)) return 0;
  
  unsigned int count = 0;
  if (removeCache) count = removeCachedProducts();
  else count = forgetAllHandles();
  
  fEvent = nullptr;
  
  return count;
} // util::ArtHandleTrackerManager<Event>::doneWithEvent()

template<typename Event >

template<typename Handle >

Handle const * util::ArtHandleTrackerManager< Event >::findHandle ( Handle const &  like ) const

private

Returns the pointer to an handle equivalent to like.

Template Parameters

Handle

the type of the handle being queried

Returns

a pointer to the handle, or nullptr if not found

This is an half-assed method since it needs to know already the exact type of the handle being queried (it's not even agnostic to the difference between art::Handle and art::ValidHandle). For this reason, it's not really useful to the users, who would probably want to know if the data product is cached, via any mean.

Technical note

Delegating the matching to util::ArtHandleTrackerInterface is not possible (like is a template parameter and can't be passed via virtual interface) and even working around that and finding the match, the returned value needs to be of type Handle, which is not necessarily the type of handle stored in the tracker.

For the full functionality of knowing if a data product is tracked, a separate registry may be kept, still complicated by the fact that part of the registry entry is a C++ type (we may need to store a sanitized std::type_info for that).

Definition at line 938 of file ArtHandleTrackerManager.h.

{
  
  // look for it, one by one
  for (TrackerPtr const& tracker: fTrackers) {
    
    
    
    std::any anyHandlePtr = tracker->handlePtr();
    Handle const** handlePtr = std::any_cast<Handle const*>(&anyHandlePtr);
    if (!handlePtr) continue; // not the right type
    
    if ((*handlePtr)->provenance()->inputTag() != like.provenance()->inputTag())
      continue; // different tag
    
    return *handlePtr;
  } // for
  
  return nullptr; // failed
  
} // util::ArtHandleTrackerManager<Event>::findTracker()

template<typename Event >

void util::ArtHandleTrackerManager< Event >::forgetAllHandles

(

)

Stops tracking any handle, without removing their cache first.

Definition at line 911 of file ArtHandleTrackerManager.h.

  { fTrackers.clear(); }

template<typename Event >

template<typename T , typename... Args>

art::Handle< T > util::ArtHandleTrackerManager< Event >::getHandle

(

Args &&...

args

)

Retrieves an handle from the event, and registers it.

Template Parameters

T	type of data product to retrieve
Args	types of the arguments needed by art::getHandle()

Parameters

args	all the arguments that art::getHandle() requires

Returns

the handle just read and being managed

See Also

getValidHandle(), registerHandle()

This function wraps art::Event::getHandle(), calling it to obtain the handle and then registering it (like with registerHandle()).

Definition at line 818 of file ArtHandleTrackerManager.h.

{
  canOperate("getHandle()");
  return registerHandle
    (fEvent->template getHandle<T>(std::forward<Args>(args)...));
}

template<typename Event >

template<typename T , typename... Args>

art::ValidHandle< T > util::ArtHandleTrackerManager< Event >::getValidHandle

(

Args &&...

args

)

Retrieves a valid handle from the event, and registers it.

Template Parameters

T	type of data product to retrieve
Args	types of the arguments needed by art::getValidHandle()

Parameters

args	all the arguments that art::getValidHandle() requires

Returns

the handle just read and being managed

See Also

getHandle(), registerHandle()

This is the art::ValidHandle sibling of getHandle(). See that one for details.

Definition at line 830 of file ArtHandleTrackerManager.h.

{
  canOperate("getValidHandle()");
  return registerHandle
    (fEvent->template getValidHandle<T>(std::forward<Args>(args)...));
}

template<typename Event >

template<typename Handle >

bool util::ArtHandleTrackerManager< Event >::handleSameProduct ( TrackerPtr  tracker, Handle const &  handle  )

staticprivate

Returns whether tracker tracks the same product that handle handles.

Definition at line 965 of file ArtHandleTrackerManager.h.

{
  using util::details::ProvenanceGetter;
  
  if (!tracker) return false;
  if (ProvenanceGetter<Handle>::productType() != tracker->productType())
    return false;
  if (ProvenanceGetter<Handle>::inputTag() != tracker->inputTag())
    return false;
  
  return true;
} // util::ArtHandleTrackerManager<>::handleSameProduct()

template<typename Event >

bool util::ArtHandleTrackerManager< Event >::hasEvent

(

)

const

Returns whether the object is associated to an event.

Definition at line 889 of file ArtHandleTrackerManager.h.

  { return fEvent; }

template<typename Event >

unsigned int util::ArtHandleTrackerManager< Event >::nTrackedHandles

(

)

const

Returns the number of handles currently tracked.

Definition at line 883 of file ArtHandleTrackerManager.h.

  { return fTrackers.size(); }

template<typename Event>

template<typename Handle >

decltype(auto) util::ArtHandleTrackerManager< Event >::registerHandle

(

Handle &&

handle

)

Registers an existing handle.

Template Parameters

Handle

the type of handle to register

Parameters

handle

the handle to be registered

Returns

handle (pass through)

This method registers a copy of handle into the manager.

template<typename Event>

template<typename Handle >

auto util::ArtHandleTrackerManager< Event >::registerHandle

(

Handle &&

handle

)

-> decltype(auto)

Definition at line 842 of file ArtHandleTrackerManager.h.

{
  using util::details::ProvenanceGetter;
  
  using Handle_t = std::decay_t<Handle>;
  
  canOperate("registerHandle()");
  
  using Tracker_t = util::details::ArtHandleTracker<Event_t, Handle_t>;
  
  // if it's already registered, we don't want to have it again
  if (auto ptr = findHandle(handle)) {
    auto const& registeredHandle = *ptr;
    mf::LogDebug msg { fConfig.logCategory };
    msg
      << "Handle<" << details::productClassOf(registeredHandle)
      << ">(" << details::inputTagOf(registeredHandle).encode()
      << ") was already registered";
    if (typeid(registeredHandle) != typeid(Handle_t)) {
      msg << " as a different handle type (" << typeid(registeredHandle).name()
        << ", now " << typeid(Handle_t).name() << ")";
    }
    msg << ".";
  }
  else {
    mf::LogDebug{ fConfig.logCategory }
      << "Registering handle<" << details::productClassOf(handle)
      << ">(" << details::inputTagOf(handle).encode()
      << ") (handle type: " << typeid(Handle_t).name() << ")."
      ;
    
    fTrackers.push_back(std::make_unique<Tracker_t>(*fEvent, handle));
  }
  
  return std::forward<Handle>(handle);
  
} // util::ArtHandleTrackerManager<>::registerHandle()

template<typename Event >

unsigned int util::ArtHandleTrackerManager< Event >::removeCachedProducts

(

)

Clears the cached data products for all tracked handles.

Returns

the number of tracked handles which had their cache removed

This method calls Event_t::removeCachedProduct() for all tracked handles. This is the core functionality of the manager, which removes the cache of all tracked handles.

The art framework always makes the handles used to remove the cache invalid (Handle::clear()). After the removal, the object stops tracking the handles (like with a call to forgetAllHandles()).

Calling this method when there are no handles registered has no effect.

Definition at line 895 of file ArtHandleTrackerManager.h.

                                                                      {
  
  // we remove cache in opposite order to registration: it's a C++ tradition.
  unsigned int const nRemoved = std::count_if(
    fTrackers.crbegin(), fTrackers.crend(),
    [](auto const& tracker){ return tracker->removeCachedProduct(); }
    );
  
  forgetAllHandles();
  
  return nRemoved;
} // util::ArtHandleTrackerManager<Event>::removeCachedProducts()

template<typename Event >

void util::ArtHandleTrackerManager< Event >::useEvent

(

Event_t const &

event

)

Changes the event being served.

Parameters

event

the new event being served

Exceptions

art::Exception

(code: art::errors::LogicError) if there are still registered handles

The object starts tracking handles of a new event.

This method requires that any pending handle has been taken care of (even if the new event happens to be the same as the old one). Common options are removeCachedProductsAndForget() if cache removal is desired, or forgetAllHandles() if it's not.

Definition at line 798 of file ArtHandleTrackerManager.h.

                                                                      {
  
  if (nTrackedHandles() > 0) {
    // since fEvent might be invalid, we don't attempt to figure out which ID
    // that event might have had
    throw art::Exception{ art::errors::LogicError }
      << "ArtHandleTrackerManager attempted to change event to "
      << event.id() << " when " << nTrackedHandles()
      << " handles are still tracked.\n";
  }
  
  fEvent = &event;
  
} // util::ArtHandleTrackerManager<Event>::useEvent()

Member Data Documentation

template<typename Event>

Config_t const util::ArtHandleTrackerManager< Event >::fConfig

private

Configuration.

Definition at line 328 of file ArtHandleTrackerManager.h.

template<typename Event>

Event_t const* util::ArtHandleTrackerManager< Event >::fEvent = nullptr

private

Event being manager. Must be present!

Definition at line 326 of file ArtHandleTrackerManager.h.

template<typename Event>

std::vector<TrackerPtr> util::ArtHandleTrackerManager< Event >::fTrackers

private

List of managed handle trackers.

Definition at line 331 of file ArtHandleTrackerManager.h.

---

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

• ArtHandleTrackerManager.h