StoreArray< T > Class Template Reference

Accessor to arrays stored in the data store. More...

#include <StoreArray.h>

Inheritance diagram for StoreArray< T >:

Collaboration diagram for StoreArray< T >:

Public Types
typedef ObjArrayIterator< TClonesArray, T >	iterator
	STL-like iterator over the T objects (not T* ).
typedef ObjArrayIterator< const TClonesArray, const T >	const_iterator
	STL-like const_iterator over the T objects (not T* ).

Public Member Functions
	StoreArray (const std::string &name="", DataStore::EDurability durability=DataStore::c_Event)
	Constructor to access an array in the DataStore.
template<class TO >
bool	registerRelationTo (const StoreArray< TO > &toArray, DataStore::EDurability durability=DataStore::c_Event, DataStore::EStoreFlags storeFlags=DataStore::c_WriteOut, const std::string &namedRelation="") const
	Register a relation to the given StoreArray.
template<class TO >
bool	requireRelationTo (const StoreArray< TO > &toArray, DataStore::EDurability durability=DataStore::c_Event, const std::string &namedRelation="") const
	Produce error if no relation from this array to 'toArray' has been registered.
template<class TO >
bool	optionalRelationTo (const StoreArray< TO > &toArray, DataStore::EDurability durability=DataStore::c_Event, const std::string &namedRelation="") const
	Tell the data store about a relation that we could make use of.
template<class TO >
bool	hasRelationTo (const StoreArray< TO > &toArray, DataStore::EDurability durability=DataStore::c_Event, const std::string &namedRelation="") const
	Check for the existence of a relation to the given StoreArray.
template<class FROM >
bool	hasRelationFrom (const StoreArray< FROM > &fromArray, DataStore::EDurability durability=DataStore::c_Event, const std::string &namedRelation="") const
	Check for the existence of a relation from the given StoreArray.
void	clear () override
	Delete all entries in this array.
int	getEntries () const
	Get the number of objects in the array.
T *	operator[] (int i) const
	Access to the stored objects.
T *	appendNew ()
	Construct a new T object at the end of the array.
template<class ... Args>
T *	appendNew (Args &&... params)
	Construct a new T object directly at the end of the array.
bool	isValid () const
	Check wether the array was registered.
	operator bool () const
	Check wether the array was registered.
TClonesArray *	getPtr () const
	Raw access to the underlying TClonesArray.
iterator	begin ()
	Return iterator to first entry.
iterator	end ()
	Return iterator to last entry +1.
const_iterator	begin () const
	Return const_iterator to first entry.
const_iterator	end () const
	Return const_iterator to last entry +1.
bool	registerInDataStore (DataStore::EStoreFlags storeFlags=DataStore::c_WriteOut)
	Register the object/array in the DataStore.
bool	registerInDataStore (const std::string &name, DataStore::EStoreFlags storeFlags=DataStore::c_WriteOut)
	Register the object/array in the DataStore.
bool	isRequired (const std::string &name="")
	Ensure this array/object has been registered previously.
bool	isOptional (const std::string &name="")
	Tell the DataStore about an optional input.
bool	assign (TObject *object, bool replace=false)
	Assign 'object' to this accessor.
const std::string &	getName () const
	Return name under which the object is saved in the DataStore.
DataStore::EDurability	getDurability () const
	Return durability with which the object is saved in the DataStore.
AccessorParams	getAccessorParams () const
	Return pair of name and durability under which stored object is saved.
virtual bool	operator== (const StoreAccessorBase &other) const
	Check if two store accessors point to the same object/array.
virtual bool	operator!= (const StoreAccessorBase &other) const
	Check if two store accessors point to a different object/array.
TClass *	getClass () const
	The underlying object's type.
bool	isArray () const
	Is this an accessor for an array?
bool	notWrittenOut () const
	Returns true if this object/array should not be saved by output modules.
std::string	readableName () const
	Convert this acessor into a readable string (for messages).

Static Public Member Functions
static std::vector< std::string >	getArrayList (DataStore::EDurability durability=DataStore::c_Event)
	Return list of array names with matching type.

Protected Attributes
std::string	m_name
	Store name under which this object/array is saved.
DataStore::EDurability	m_durability
	Store durability under which the object/array is saved.
TClass *	m_class
	The underlying object's type.
bool	m_isArray
	Is this an accessor for an array?

Private Member Functions
bool	create (bool replace=false)
	Creating StoreArrays is unnecessary, only used internally.
T *	nextFreeAdress ()
	Returns address of the next free position of the array.
void	ensureAttached () const
	Ensure that this object is attached.
void	ensureCreated () const
	Ensure that the array has been created.
bool	isCreated () const
	Check wether the array object was created.

Private Attributes
TClonesArray **	m_storeArray
	Pointer that actually holds the TClonesArray.

Detailed Description

template<class T>
class Belle2::StoreArray< T >

Accessor to arrays stored in the data store.

StoreArrays (like StoreObjPtrs) are uniquely identified by their name and durability. In most cases, arrays are created with durability DataStore::c_Event and the default name corresponding to their type. (i.e. typename + 's') Thus, calling the constructor StoreArray<MyType>() will connect this StoreArray with the array called 'MyTypes' in the data store, with a lifetime of one event.

Accessing elements of an existing array

Stored objects can be accessed directly using their array index and operator[]. For example, the following code snippet loops over all entries in an array of CDCSimHits:

StoreArray<CDCSimHit> cdcsimhits;
//loop over all CDC simhits
for(int iCDC = 0; iCDC < cdcsimhits.getEntries(); iCDC++) {
  const CDCSimHit* hit = cdcsimhits[iCDC]; //get iCDC'th entry in StoreArray
  // Use hit's data here...
}
 
//or using range-based for:
for(const CDCSimHit& hit : cdcsimhits) {
  // Use hit's data here...
}

Note

Remember to use references or pointers when iterating, otherwise accessing, e.g., relations will not work.

Objects linked together using relations can also be obtained by querying the objects themselves, since they should derive from RelationsObject (See class documentation for usage examples.)

Adding elements

Elements can be added to the array in a few ways. The easiest is to use something like:

StoreArray<CDCSimHit> cdcsimhits;
//...
CDCSimHit* newhit = cdcsimhits.appendNew();
//fill newhit with data here...

appendNew() can also use non-default constructors, e.g. if there is a constructor that takes the arguments (int, float), you can use appendNew(int, float) instead.

Registration of arrays

Note that you have to register an array in the initialize method of a module first (using registerInDataStore()) before you can use it. This procedure is the same as for objects handled by StoreObjPtr.

Using StoreArray as a module member variable

To avoid some overhead involved in re-creating the StoreArray e.g. in each event() function call, you can also make StoreArray a member variable of your class. If it is of non-event durability, you'll need to add the appropriate constructor call to the initializer list, e.g. (here with default name):

MyModule::MyModule():
  m_fooHits("", DataStore::c_Persistent)
{}

In initialize(), you should also use registerInDataStore() or isOptional()/isRequired() to specify wether it is an input or output. For non-default names (which you might not know in the constructor, e.g. in the case of module parameters), set the 'name' argument of any of these three functions to permanently bind the StoreArray to the array with the given name.

See also

Objects in different arrays can be linked using relations, see RelationsInterface, RelationsObject

See StoreObjPtr for a way store single objects

Data can also be accessed from Python modules using PyStoreArray

While individual elements cannot be removed directly from StoreArray, SelectSubset can be used to filter it.

Definition at line 113 of file StoreArray.h.

Member Typedef Documentation

const_iterator

typedef ObjArrayIterator<const TClonesArray, const T> const_iterator

STL-like const_iterator over the T objects (not T* ).

Definition at line 118 of file StoreArray.h.

iterator

typedef ObjArrayIterator<TClonesArray, T> iterator

STL-like iterator over the T objects (not T* ).

Definition at line 116 of file StoreArray.h.

Constructor & Destructor Documentation

StoreArray()

StoreArray ( const std::string &  name = "", DataStore::EDurability  durability = DataStore::c_Event  )

inlineexplicit

Constructor to access an array in the DataStore.

Parameters

name	Name under which the array is stored in the DataStore. If an empty string is supplied, the type name will be used.
durability	Decides durability map used for getting the accessed array.

Definition at line 126 of file StoreArray.h.

                                                                                                       :
      StoreAccessorBase(DataStore::arrayName<T>(name), durability, T::Class(), true), m_storeArray(0) {}

Member Function Documentation

appendNew() [1/2]

T * appendNew ( )

inline

Construct a new T object at the end of the array.

Appends a new object to the array, and returns a pointer so it can be filled with data. The default constructor is used for the object's creation.

Returns

pointer to the created object

Definition at line 246 of file StoreArray.h.

{ return new (nextFreeAdress()) T(); }

appendNew() [2/2]

T * appendNew ( Args &&...  params )

inline

Construct a new T object directly at the end of the array.

This is done by forwarding all arguments to the constructor of the type T. If there is a constructor which takes the given combination of arguments then this call will succeed, otherwise it fails on compilation.

This method imposes no overhead as no temporary has to be constructed and should be the preferred solution for creating new objects.

It handles just like the (C++11) standard library's emplace..() functions:

myStoreArray.appendNew(some ctor arguments);

Note

since all arguments are passed to the constructor of class T, doing something like appendNew(T(ctor arguments)) is unnecessary. This would construct a temporary object of class T, then copy-construct another T object in the array and destroy the temporary object again.

Returns

pointer to the created object

Definition at line 268 of file StoreArray.h.

    {
      return new (nextFreeAdress()) T(std::forward<Args>(params)...);
    }

assign()

bool assign ( TObject *  object, bool  replace = false  )

inherited

Assign 'object' to this accessor.

(takes ownership).

Parameters

object	The object that should be put in the DataStore, should be of same type as the one used by this accessor.
replace	Should an existing object be replaced? (if existing and supplied object are equal, this has no effect)

Returns

True if the assignment succeeded. If false, assign() will delete 'object', do not use it afterwards.

Definition at line 33 of file StoreAccessorBase.cc.

{
  if (not object)
    return false;
 
  bool success = false;
  const bool objIsArray = (object->IsA() == TClonesArray::Class());
  TClass* objClass = objIsArray ? (static_cast<TClonesArray*>(object))->GetClass() : object->IsA();
  if (objIsArray != isArray()) {
    B2ERROR("Cannot assign an object to an array (or vice versa); while assigning to " << readableName());
  } else if (objClass != getClass()) {
    B2ERROR("Cannot assign() an object of type '" << objClass->GetName() << "' to " << readableName() << " of type '" <<
            getClass()->GetName() << "'!");
  } else {
    success = DataStore::Instance().createObject(object, replace, *this);
  }
  if (!success)
    delete object;
  return success;
}

begin() [1/2]

iterator begin ( )

inline

Return iterator to first entry.

Definition at line 318 of file StoreArray.h.

{ ensureAttached(); return iterator(m_storeArray); }

begin() [2/2]

const_iterator begin ( ) const

inline

Return const_iterator to first entry.

Definition at line 323 of file StoreArray.h.

{ ensureAttached(); return const_iterator(m_storeArray); }

clear()

void clear ( )

inlineoverridevirtual

Delete all entries in this array.

Any relations to objects in this array are also removed.

Reimplemented from StoreAccessorBase.

Definition at line 207 of file StoreArray.h.

    {
      if (getEntries() != 0) {
        (*m_storeArray)->Delete();
        _StoreArrayImpl::clearRelations(*this);
      }
    }

create()

bool create ( bool  replace = false )

inlineprivate

Creating StoreArrays is unnecessary, only used internally.

Definition at line 329 of file StoreArray.h.

{ return StoreAccessorBase::create(replace); }

end() [1/2]

iterator end ( )

inline

Return iterator to last entry +1.

Definition at line 320 of file StoreArray.h.

{ ensureAttached(); return iterator(m_storeArray, true); }

end() [2/2]

const_iterator end ( ) const

inline

Return const_iterator to last entry +1.

Definition at line 325 of file StoreArray.h.

{ ensureAttached(); return const_iterator(m_storeArray, true); }

ensureAttached()

void ensureAttached ( ) const

inlineprivate

Ensure that this object is attached.

Definition at line 342 of file StoreArray.h.

    {
      if (!m_storeArray) {
        const_cast<StoreArray*>(this)->m_storeArray = reinterpret_cast<TClonesArray**>(DataStore::Instance().getObject(*this));
      }
    }

ensureCreated()

void ensureCreated ( ) const

inlineprivate

Ensure that the array has been created.

Called automatically by write operations.

Definition at line 352 of file StoreArray.h.

    {
      if (!isCreated()) {
        if (!const_cast<StoreArray*>(this)->create())
          throw std::runtime_error("Write access to " + readableName() + " failed, did you remember to call registerInDataStore()?");
      }
    }

getAccessorParams()

AccessorParams getAccessorParams ( ) const

inlineinherited

Return pair of name and durability under which stored object is saved.

Definition at line 134 of file StoreAccessorBase.h.

{ return make_pair(m_name, m_durability);}

getArrayList()

static std::vector< std::string > getArrayList ( DataStore::EDurability  durability = DataStore::c_Event )

inlinestatic

Return list of array names with matching type.

Definition at line 275 of file StoreArray.h.

    {
      return DataStore::Instance().getListOfArrays(T::Class(), durability);
    }

getClass()

TClass * getClass ( ) const

inlineinherited

The underlying object's type.

Definition at line 149 of file StoreAccessorBase.h.

{ return m_class; }

getDurability()

DataStore::EDurability getDurability ( ) const

inlineinherited

Return durability with which the object is saved in the DataStore.

Definition at line 131 of file StoreAccessorBase.h.

{ return m_durability; }

getEntries()

int getEntries ( ) const

inline

Get the number of objects in the array.

Definition at line 216 of file StoreArray.h.

{ return isCreated() ? ((*m_storeArray)->GetEntriesFast()) : 0;}

getName()

const std::string & getName ( ) const

inlineinherited

Return name under which the object is saved in the DataStore.

Definition at line 128 of file StoreAccessorBase.h.

{ return m_name; }

getPtr()

TClonesArray * getPtr ( ) const

inline

Raw access to the underlying TClonesArray.

Warning

TClonesArray is dangerously easy to misuse. Whatever you do will probably be slow, leak memory, and murder your pets. In most cases, you'll want to use StoreArray functions like operator[], getEntries() or appendNew() instead.

Returns

pointer to TClonesArray, or NULL if this array was not registered in the data store

Definition at line 311 of file StoreArray.h.

    {
      ensureCreated();
      return (m_storeArray ? *m_storeArray : nullptr);
    }

hasRelationFrom()

bool hasRelationFrom ( const StoreArray< FROM > &  fromArray, DataStore::EDurability  durability = DataStore::c_Event, const std::string &  namedRelation = ""  ) const

inline

Check for the existence of a relation from the given StoreArray.

Parameters

fromArray	Array the relation should point to (from this StoreArray)
durability	Durability of the relation.
namedRelation	Additional name for the relation, or "" for the default naming

Definition at line 197 of file StoreArray.h.

    {
      return DataStore::Instance().hasRelation(fromArray, *this, durability, namedRelation);
    }

hasRelationTo()

bool hasRelationTo ( const StoreArray< TO > &  toArray, DataStore::EDurability  durability = DataStore::c_Event, const std::string &  namedRelation = ""  ) const

inline

Check for the existence of a relation to the given StoreArray.

Parameters

toArray	Array the relation should point to (from this StoreArray)
durability	Durability of the relation.
namedRelation	Additional name for the relation, or "" for the default naming

Definition at line 185 of file StoreArray.h.

    {
      return DataStore::Instance().hasRelation(*this, toArray, durability, namedRelation);
    }

isArray()

bool isArray ( ) const

inlineinherited

Is this an accessor for an array?

Definition at line 152 of file StoreAccessorBase.h.

{ return m_isArray; }

isCreated()

bool isCreated ( ) const

inlineprivate

Check wether the array object was created.

Definition at line 361 of file StoreArray.h.

    {
      ensureAttached();
      return m_storeArray && *m_storeArray;
    }

isOptional()

bool isOptional ( const std::string &  name = "" )

inlineinherited

Tell the DataStore about an optional input.

Mainly useful for creating diagrams of module inputs and outputs.

Parameters

name	If not empty, set non-default name for this object/array. This is permanent, so that e.g. after using registerInDataStore("myName") in initialize(), this object will continue refer to 'myName' in event().

Returns

True if the object/array exists.

Definition at line 93 of file StoreAccessorBase.h.

    {
      if (!name.empty())
        m_name = name;
      return DataStore::Instance().optionalInput(*this);
    }

isRequired()

bool isRequired ( const std::string &  name = "" )

inlineinherited

Ensure this array/object has been registered previously.

Will cause an ERROR if it does not exist. This must be called in the initialization phase.

Parameters

name	If not empty, set non-default name for this object/array. This is permanent, so that e.g. after using registerInDataStore("myName") in initialize(), this object will continue refer to 'myName' in event().

Returns

True if the object/array exists.

Definition at line 78 of file StoreAccessorBase.h.

    {
      if (!name.empty())
        m_name = name;
      return DataStore::Instance().requireInput(*this);
    }

isValid()

bool isValid ( ) const

inline

Check wether the array was registered.

Note

Iterating over the array or calling getEntries() is safe even if this returns false. (getEntries() will return 0)

Returns

True if the array was registered.

Definition at line 288 of file StoreArray.h.

    {
      ensureAttached();
      return m_storeArray;
    }

nextFreeAdress()

T * nextFreeAdress ( )

inlineprivate

Returns address of the next free position of the array.

Returns

pointer to address just past the last array element

Definition at line 335 of file StoreArray.h.

    {
      ensureCreated();
      return static_cast<T*>((*m_storeArray)->AddrAt(getEntries()));
    }

notWrittenOut()

bool notWrittenOut ( ) const

inherited

Returns true if this object/array should not be saved by output modules.

See DataStore::c_DontWriteOut. Can be changed by re-registering it with/without the flag.

Definition at line 53 of file StoreAccessorBase.cc.

{
  const DataStore::StoreEntry* entry = DataStore::Instance().getEntry(*this);
  if (!entry) {
    B2ERROR("notWrittenOut(): " << readableName() << " doesn't seem to  be registered");
    return false;
  }
  return entry->dontWriteOut;
}

operator bool()

operator bool ( ) const

inline

Check wether the array was registered.

Note

Iterating over the array or calling getEntries() is safe even if this returns false. (getEntries() will return 0)

Returns

True if the array was registered.

Definition at line 301 of file StoreArray.h.

{ return isValid(); }

operator!=()

virtual bool operator!= ( const StoreAccessorBase &  other ) const

inlinevirtualinherited

Check if two store accessors point to a different object/array.

Definition at line 143 of file StoreAccessorBase.h.

    {
      return !(*this == other);
    }

operator==()

virtual bool operator== ( const StoreAccessorBase &  other ) const

inlinevirtualinherited

Check if two store accessors point to the same object/array.

Definition at line 137 of file StoreAccessorBase.h.

    {
      return getAccessorParams() == other.getAccessorParams();
    }

operator[]()

T * operator[] ( int  i ) const

inline

Access to the stored objects.

Out-of-bounds accesses throw an std::out_of_range exception

Note that using iterators (or range-based for) avoids the range-check internally, and thus might be slightly faster.

Parameters

i	Array index, should be in 0..getEntries()-1

Returns

pointer to the object

Definition at line 228 of file StoreArray.h.

    {
      ensureCreated();
      //At() checks for out-of-range and returns NULL in that case
      TObject* obj = (*m_storeArray)->At(i);
      if (obj == nullptr)
        throw std::out_of_range("Out-of-range access in StoreArray::operator[], for " + readableName() + ", index " + std::to_string(i));
      return static_cast<T*>(obj); //type was checked by DataStore, so the cast is safe.
    }

optionalRelationTo()

bool optionalRelationTo ( const StoreArray< TO > &  toArray, DataStore::EDurability  durability = DataStore::c_Event, const std::string &  namedRelation = ""  ) const

inline

Tell the data store about a relation that we could make use of.

(aka. optional input)

Mainly useful for creating diagrams of module inputs and outputs.

Parameters

toArray	Array the relation should point to (from this StoreArray)
durability	Durability of the relation.
namedRelation	Additional name for the relation, or "" for the default naming

Returns

True if the relations exists.

Definition at line 172 of file StoreArray.h.

    {
      return DataStore::Instance().optionalRelation(*this, toArray, durability, namedRelation);
    }

readableName()

std::string readableName ( ) const

inherited

Convert this acessor into a readable string (for messages).

e.g. "object EventMetaData (durability: event)"

Definition at line 18 of file StoreAccessorBase.cc.

{
  std::string str(isArray() ? "array" : "object");
  str += " '" + getName() + "' (durability: ";
  switch (getDurability()) {
    case DataStore::c_Event:
      str += "event";
      break;
    case DataStore::c_Persistent:
      str += "persistent";
      break;
  }
  return str + ")";
}

registerInDataStore() [1/2]

bool registerInDataStore ( const std::string &  name, DataStore::EStoreFlags  storeFlags = DataStore::c_WriteOut  )

inlineinherited

Register the object/array in the DataStore.

This must be called in the initialization phase.

Parameters

name	If not empty, set non-default name for this object/array. This is permanent, so that e.g. after using registerInDataStore("myName") in initialize(), this object will continue refer to 'myName' in event().
storeFlags	ORed combination of DataStore::EStoreFlags.

Returns

True if the registration succeeded.

Definition at line 64 of file StoreAccessorBase.h.

    {
      if (!name.empty())
        m_name = name;
      return DataStore::Instance().registerEntry(m_name, m_durability, getClass(), isArray(), storeFlags);
    }

registerInDataStore() [2/2]

bool registerInDataStore ( DataStore::EStoreFlags  storeFlags = DataStore::c_WriteOut )

inlineinherited

Register the object/array in the DataStore.

This must be called in the initialization phase.

Parameters

storeFlags

ORed combination of DataStore::EStoreFlags.

Returns

True if the registration succeeded.

Definition at line 52 of file StoreAccessorBase.h.

    {
      return DataStore::Instance().registerEntry(m_name, m_durability, getClass(), isArray(), storeFlags);
    }

registerRelationTo()

bool registerRelationTo ( const StoreArray< TO > &  toArray, DataStore::EDurability  durability = DataStore::c_Event, DataStore::EStoreFlags  storeFlags = DataStore::c_WriteOut, const std::string &  namedRelation = ""  ) const

inline

Register a relation to the given StoreArray.

Use this if you want to create relate objects in this array to objects in 'toArray'. Must be called in the initialization phase.

Parameters

toArray	Array the relation should point to (from this StoreArray)
durability	Durability of the relation.
storeFlags	ORed combination of DataStore::EStoreFlags
namedRelation	Additional name for the relation, or "" for the default naming

Definition at line 140 of file StoreArray.h.

    {
      return DataStore::Instance().registerRelation(*this, toArray, durability, storeFlags, namedRelation);
    }

requireRelationTo()

bool requireRelationTo ( const StoreArray< TO > &  toArray, DataStore::EDurability  durability = DataStore::c_Event, const std::string &  namedRelation = ""  ) const

inline

Produce error if no relation from this array to 'toArray' has been registered.

Must be called in initialization phase, aborts job if it fails. (allowing you to catch problems early)

Parameters

toArray	Array the relation should point to (from this StoreArray)
durability	Durability of the relation.
namedRelation	Additional name for the relation, or "" for the default naming

Returns

True if the relations exists.

Definition at line 155 of file StoreArray.h.

    {
      return DataStore::Instance().requireRelation(*this, toArray, durability, namedRelation);
    }

Member Data Documentation

m_class

TClass* m_class

protectedinherited

The underlying object's type.

Definition at line 172 of file StoreAccessorBase.h.

m_durability

DataStore::EDurability m_durability

protectedinherited

Store durability under which the object/array is saved.

Definition at line 169 of file StoreAccessorBase.h.

m_isArray

bool m_isArray

protectedinherited

Is this an accessor for an array?

Definition at line 175 of file StoreAccessorBase.h.

m_name

std::string m_name

protectedinherited

Store name under which this object/array is saved.

Definition at line 166 of file StoreAccessorBase.h.

m_storeArray

TClonesArray** m_storeArray

private

Pointer that actually holds the TClonesArray.

Definition at line 368 of file StoreArray.h.

---

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

• framework/datastore/include/RelationArray.h
• framework/datastore/include/StoreArray.h