D3PD variable metadata handling class. More...

#include <ObjectMetadata.h>

Inheritance diagram for D3PD::ObjectMetadata:

Collaboration diagram for D3PD::ObjectMetadata:

Classes
class	Variable
	Internal class keeping track of a single variable. More...

Public Member Functions
	ObjectMetadata ()
	Default constructor.
	ObjectMetadata (const ObjectMetadata &parent)
	Copy constructor.
ObjectMetadata &	operator= (const ObjectMetadata &parent)
	Assignment operator.
bool	operator== (const ObjectMetadata &rhs) const
	Equality operator.
bool	operator< (const ObjectMetadata &rhs) const
	Operator needed to use such objects in ordered STL containers.
virtual StatusCode	addVariable (const std::string &name, const std::type_info &ti, void &ptr, std::string_view docstring="", const void defval=0)
	This function can be used to save the metadata about a D3PD variable.
virtual StatusCode	addDimensionedVariable (const std::string &name, const std::type_info &ti, void &ptr, const std::string &dim, std::string_view docstring="", const void defval=0)
	The object doesn't support dimensioned variables at the moment, like most of the D3PDMaker code doesn't.
const std::string &	name () const
	Get the name of the D3PDObject that this object describes.
void	setName (const std::string &name)
	Set the name of the D3PDObject that this object describes.
std::string metadataName	ATLAS_NOT_THREAD_SAFE () const
	Get the name for the metadata object that should be created.
const std::string &	prefix () const
	Get the prefix given to variables in this D3PDObject.
void	setPrefix (const std::string &prefix)
	Set the prefix given to variables in this D3PDObject.
bool	container () const
	Get whether the D3PDObject describes a container or not.
void	setContainer (bool container)
	Set whether the D3PDObject describes a container or not.
std::string	toString () const
	Function "serializing" the stored information into a string.
StatusCode	read (const std::string &data)
	Function "de-serializing" the stored information from a string.
void	clear ()
	Function clearing the object.
ObjectMetadata &	operator+= (const ObjectMetadata &obj)
	Operator merging the contents of two objects.
ObjectMetadata &	merge (const ObjectMetadata &obj)
	Function merging the contents of two objects.
const std::set< Variable > &	variables () const
	Function for accessing all the variables of the D3PDObject.
template<class T>
StatusCode	addVariable (const std::string &name, T *&ptr, std::string_view docstring="")
	Make the template implementation from `IAddVariable` visible.
template<class T, class U>
StatusCode	addVariable (const std::string &name, T *&ptr, std::string_view docstring, const U &defval)
	Make the template implementation from `IAddVariable` visible.
template<class T>
StatusCode	addDimensionedVariable (const std::string &name, T *&ptr, const std::string &dim, std::string_view docstring="")
	Add a variable to the tuple.
template<class T, class U>
StatusCode	addDimensionedVariable (const std::string &name, T *&ptr, const std::string &dim, std::string_view docstring, const U &defval)
	Add a variable to the tuple.

Static Public Member Functions
static std::string	objectName (const std::string &metaName)
	Get the D3PDObject's name from the name of the metadata object.

Static Public Attributes
static const size_t	RANDOM_NAME_POSTFIX_LENGTH = 6
	Length of the random string appended to the object name.
static const char *const	STRING_SEPARATOR = "@"
	Character separating parts of the object's metadata.
static const unsigned int	SERIALIZER_VERSION = 1
	"Version number" of the serialized information

Protected Attributes
std::set< Variable >	m_variables
	The list of variables created by a D3PDObject.
std::string	m_name
	Name of the D3PDObject that this object describes.
std::string	m_prefix
	Prefix used by the D3PDObject.
bool	m_container
	The D3PDObject describes a container.

Static Private Member Functions
static std::string genSuffix	ATLAS_NOT_THREAD_SAFE (const std::string &name, size_t length)
	Generate a unique suffix for a metadata object name.

Detailed Description

D3PD variable metadata handling class.

   This class is used to store information in D3PD files about the
   variables that were created using a single D3PDObject in the job.
   The created metadata can be used to create D3PDReader classes
   later on, independent of the storage technology and the language
   used.

Author: Attila Krasznahorkay Attil.nosp@m.a.Kr.nosp@m.aszna.nosp@m.hork.nosp@m.ay@ce.nosp@m.rn.c.nosp@m.h

Definition at line 36 of file ObjectMetadata.h.

Constructor & Destructor Documentation

◆ ObjectMetadata() [1/2]

D3PD::ObjectMetadata::ObjectMetadata ( )

Default constructor.

Definition at line 62 of file ObjectMetadata.cxx.

      : m_variables(), m_name( "" ), m_prefix( "" ),
        m_container( false ) {
 
   }

◆ ObjectMetadata() [2/2]

D3PD::ObjectMetadata::ObjectMetadata ( const ObjectMetadata & parent )

Copy constructor.

Definition at line 68 of file ObjectMetadata.cxx.

      : m_variables( parent.m_variables ), m_name( parent.m_name ),
        m_prefix( parent.m_prefix ), m_container( parent.m_container ) {
 
   }

Member Function Documentation

◆ addDimensionedVariable() [1/3]

StatusCode D3PD::ObjectMetadata::addDimensionedVariable	(	const std::string &	name,
		const std::type_info &	ti,
		void *&	ptr,
		const std::string &	dim,
		std::string_view	docstring = "",
		const void *	defval = 0 )

virtual

The object doesn't support dimensioned variables at the moment, like most of the D3PDMaker code doesn't.

Still, we might implement something like this later on.

Implements D3PD::IAddVariable.

Definition at line 158 of file ObjectMetadata.cxx.

                                                           {
 
      REPORT_MESSAGE_WITH_CONTEXT( MSG::FATAL, "ObjectMetadata" )
         << "addDimensionedVariable(...) not implemented";
 
      return StatusCode::FAILURE;
   }

◆ addDimensionedVariable() [2/3]

template<class T, class U>

StatusCode D3PD::IAddVariable::addDimensionedVariable	(	const std::string &	name,
		T *&	ptr,
		const std::string &	dim,
		std::string_view	docstring,
		const U &	defval )

Add a variable to the tuple.

Parameters

name	The name of the variable.
ptr	Pointer to the type of the variable. The pointer need not be initialized; the D3PD software will set the pointer prior to calling `fill()`.
dim	Dimension for the variable. (Presently unimplemented!)
docstring	Documentation string for this variable.
defval	Pointer to the default value to use for this variable. Only works for basic types.

If called from the constructor, the only effect is to clear ptr.

◆ addDimensionedVariable() [3/3]

template<class T>

StatusCode D3PD::IAddVariable::addDimensionedVariable	(	const std::string &	name,
		T *&	ptr,
		const std::string &	dim,
		std::string_view	docstring = "" )

Add a variable to the tuple.

Parameters

name	The name of the variable.
ptr	Pointer to the type of the variable. The pointer need not be initialized; the D3PD software will set the pointer prior to calling `fill()`.
dim	Dimension for the variable. (Presently unimplemented!)
docstring	Documentation string for this variable.

If called from the constructor, the only effect is to clear ptr.

◆ addVariable() [1/3]

StatusCode D3PD::ObjectMetadata::addVariable	(	const std::string &	name,
		const std::type_info &	ti,
		void *&	ptr,
		std::string_view	docstring = "",
		const void *	defval = 0 )

virtual

This function can be used to save the metadata about a D3PD variable.

Note that this class doesn't implement the full might of an ID3PD object, so no new object is created as a result of this function call. This means that it should always be followed by calling the addVariable(...) function of a proper IAddVariable object.

Implements D3PD::IAddVariable.

Definition at line 110 of file ObjectMetadata.cxx.

                                                           {
 
      // Check that the variable has the correct prefix:
      if( m_prefix != "" &&
          !name.starts_with( m_prefix) )
      {
         REPORT_MESSAGE_WITH_CONTEXT( MSG::ERROR, "ObjectMetadata" )
            << "Specified variable name (" << name << ") doesn't have the "
            << "expected prefix (" << m_prefix << ")";
         return StatusCode::RECOVERABLE;
      }
 
      // Create a new variable:
      Variable var;
 
      // Remove the prefix from the variable name:
      var.setName( name.substr( m_prefix.size(), name.npos ) );
 
      // Check if it's already amongst the existing variables:
      if( m_variables.find( var ) != m_variables.end() ) {
         return StatusCode::SUCCESS;
      }
 
      // Set the type of the variable:
      var.setType( System::typeinfoName( ti.name() ) );
 
      // Set whether the variable is a primitive:
      var.setPrimitive( isPrimitive( ti ) );
 
      // Set the documentation string for the variable:
      var.setDoc( docstring );
 
      // Remember the variable:
      m_variables.insert( std::move(var) );
 
      return StatusCode::SUCCESS;
   }

◆ addVariable() [2/3]

template<class T, class U>

StatusCode D3PD::IAddVariable::addVariable	(	const std::string &	name,
		T *&	ptr,
		std::string_view	docstring,
		const U &	defval )

Make the template implementation from IAddVariable visible.

◆ addVariable() [3/3]

template<class T>

StatusCode D3PD::IAddVariable::addVariable	(	const std::string &	name,
		T *&	ptr,
		std::string_view	docstring = "" )

Make the template implementation from IAddVariable visible.

◆ ATLAS_NOT_THREAD_SAFE() [1/2]

std::string metadataName D3PD::ObjectMetadata::ATLAS_NOT_THREAD_SAFE ( ) const

Get the name for the metadata object that should be created.

◆ ATLAS_NOT_THREAD_SAFE() [2/2]

std::string genSuffix D3PD::ObjectMetadata::ATLAS_NOT_THREAD_SAFE	(	const std::string &	name,
		size_t	length )

staticprivate

Generate a unique suffix for a metadata object name.

Parameters

name	The metadata object name.
length	The length of the suffix to add.

We used to do this by generating a random string. However, this is very bad for regression testing, as adding or removing one variable can then change the names of all subsequent variables. Instead, we generate the suffix based on a count of the number of times we've seen a particular name.

◆ clear()

void D3PD::ObjectMetadata::clear ( )

Function clearing the object.

Definition at line 353 of file ObjectMetadata.cxx.

                              {
 
      // Clear/reset all the variables:
      m_variables.clear();
      m_name = "";
      m_prefix = "";
      m_container = false;
 
      return;
   }

◆ container()

bool D3PD::ObjectMetadata::container ( ) const

Get whether the D3PDObject describes a container or not.

Definition at line 231 of file ObjectMetadata.cxx.

                                        {
 
      return m_container;
   }

◆ merge()

ObjectMetadata & D3PD::ObjectMetadata::merge ( const ObjectMetadata & obj )

Function merging the contents of two objects.

This merging function was implemented in the anticipation that it might come in handy later on.

But no guarantees...

Parameters

obj	The object that should be merged with this one

Returns: A reference to the current object

Definition at line 376 of file ObjectMetadata.cxx.

                                                                    {
 
      // Only objects with the same "name" should be merged:
      if( name() != obj.name() ) {
         REPORT_MESSAGE_WITH_CONTEXT( MSG::WARNING, "ObjectMetadata" )
            << "Can't merge object with name \"" << obj.name()
            << "\" into another object with name \"" << name() << "\"";
         return *this;
      }
 
      // Now merge all the variable definitions:
      std::set< Variable >::const_iterator itr = obj.variables().begin();
      std::set< Variable >::const_iterator end = obj.variables().end();
      for( ; itr != end; ++itr ) {
         m_variables.insert( *itr );
      }
 
      return *this;
   }

◆ name()

const std::string & D3PD::ObjectMetadata::name ( ) const

Get the name of the D3PDObject that this object describes.

Definition at line 171 of file ObjectMetadata.cxx.

                                               {
 
      return m_name;
   }

◆ objectName()

std::string D3PD::ObjectMetadata::objectName ( const std::string & metaName )

static

Get the D3PDObject's name from the name of the metadata object.

This function should be used by the client code to "decode" the name of the original D3PDObject from the name of the metadata object.

This way the client code doesn't have to know how this class works internally.

Parameters

metaName The name of the metadata object in the D3PD file

Returns: The name of the original D3PDObject that the metadata object describes

Definition at line 214 of file ObjectMetadata.cxx.

                                                                   {
 
      return metaName.substr( 0, metaName.size() -
                              ( RANDOM_NAME_POSTFIX_LENGTH + 1 ) );
   }

◆ operator+=()

ObjectMetadata & D3PD::ObjectMetadata::operator+= ( const ObjectMetadata & obj )

Operator merging the contents of two objects.

Definition at line 364 of file ObjectMetadata.cxx.

                                                                        {
 
      return this->merge( obj );
   }

◆ operator<()

bool D3PD::ObjectMetadata::operator< ( const ObjectMetadata & rhs ) const

Operator needed to use such objects in ordered STL containers.

Definition at line 92 of file ObjectMetadata.cxx.

                                                                    {
 
      if( prefix() != rhs.prefix() ) {
         return ( prefix() < rhs.prefix() );
      } else if( name() != rhs.name() ) {
         return ( name() < rhs.name() );
      } else {
         return ( container() < rhs.container() );
      }
   }

◆ operator=()

ObjectMetadata & D3PD::ObjectMetadata::operator= ( const ObjectMetadata & parent )

Assignment operator.

Definition at line 74 of file ObjectMetadata.cxx.

   {
     if (&parent != this) {
       m_variables = parent.m_variables;
       m_name      = parent.m_name;
       m_prefix    = parent.m_prefix;
       m_container = parent.m_container;
     }
 
      return *this;
   }

◆ operator==()

bool D3PD::ObjectMetadata::operator== ( const ObjectMetadata & rhs ) const

Equality operator.

Definition at line 86 of file ObjectMetadata.cxx.

                                                                   {
 
      return ( ( name() == rhs.name() ) && ( prefix() == rhs.prefix() ) &&
               ( container() == rhs.container() ) );
   }

◆ prefix()

const std::string & D3PD::ObjectMetadata::prefix ( ) const

Get the prefix given to variables in this D3PDObject.

Definition at line 220 of file ObjectMetadata.cxx.

                                                 {
 
      return m_prefix;
   }

◆ read()

StatusCode D3PD::ObjectMetadata::read ( const std::string & data )

Function "de-serializing" the stored information from a string.

This function can be used to read in information from a serialized form.

Note that the function doesn't clear the contents of the object. So it can be used to merge information from multiple metadata objects / files.

Parameters

data	The string that should be decoded

Returns: StatusCode::SUCCESS if the operation was successful, StatusCode::FAILURE otherwise

Definition at line 277 of file ObjectMetadata.cxx.

                                                          {
 
      //
      // Tokenize the string using Boost:
      //
      boost::char_separator< char > separator( STRING_SEPARATOR, "",
                                               boost::keep_empty_tokens );
      boost::tokenizer< boost::char_separator< char > > tokens( data,
                                                                separator );
      boost::tokenizer< boost::char_separator< char > >::const_iterator itr = tokens.begin();
      boost::tokenizer< boost::char_separator< char > >::const_iterator end = tokens.end();
 
      // Check that we didn't reach the last token yet:
      if( itr == end ) {
         REPORT_MESSAGE_WITH_CONTEXT( MSG::FATAL, "ObjectMetadata" )
            << "The received data can not be parsed successfully: "
            << data;
         return StatusCode::FAILURE;
      }
 
      // Check that the metadata was saved using the same version of the
      // serializer code. Later on we might want to introduce backward
      // compatibility, but for now this simple check should be enough.
      if( atoi(itr->c_str()) != SERIALIZER_VERSION ) {
         REPORT_MESSAGE_WITH_CONTEXT( MSG::FATAL, "ObjectMetadata" )
            << "Version mismatch! The metadata was saved with a different "
            << "serialization version (" << *itr << ") than the code used ("
            << SERIALIZER_VERSION << ")";
         return StatusCode::FAILURE;
      }
 
      ++itr;
 
      // Check that we didn't reach the last token yet:
      if( itr == end ) {
         REPORT_MESSAGE_WITH_CONTEXT( MSG::FATAL, "ObjectMetadata" )
            << "The received data can not be parsed successfully: "
            << data;
         return StatusCode::FAILURE;
      }
 
      // Extract the prefix from the metadata:
      m_prefix = *itr; ++itr;
 
      // Check that we didn't reach the last token yet:
      if( itr == end ) {
         REPORT_MESSAGE_WITH_CONTEXT( MSG::FATAL, "ObjectMetadata" )
            << "The received data can not be parsed successfully: "
            << data;
         return StatusCode::FAILURE;
      }
 
      // Extract whether this is a container that the variables describe:
      if( *itr == "0" ) {
         m_container = false;
      } else if( *itr == "1" ) {
         m_container = true;
      } else {
         REPORT_MESSAGE_WITH_CONTEXT( MSG::FATAL, "ObjectMetadata" )
            << "The received data can not be parsed successfully: "
            << data;
         return StatusCode::FAILURE;
      }
 
      ++itr;
 
      // Finally, let's extract all the variable metadata:
      for( ; itr != end; ++itr ) {
         Variable var;
         CHECK( var.read( *itr ) );
         m_variables.insert( std::move(var) );
      }
 
      return StatusCode::SUCCESS;
   }

◆ setContainer()

void D3PD::ObjectMetadata::setContainer ( bool container )

Set whether the D3PDObject describes a container or not.

Definition at line 236 of file ObjectMetadata.cxx.

                                                     {
 
      m_container = container;
      return;
   }

◆ setName()

void D3PD::ObjectMetadata::setName ( const std::string & name )

Set the name of the D3PDObject that this object describes.

Definition at line 176 of file ObjectMetadata.cxx.

                                                       {
 
      m_name = name;
      return;
   }

◆ setPrefix()

void D3PD::ObjectMetadata::setPrefix ( const std::string & prefix )

Set the prefix given to variables in this D3PDObject.

Definition at line 225 of file ObjectMetadata.cxx.

                                                           {
 
      m_prefix = prefix;
      return;
   }

◆ toString()

std::string D3PD::ObjectMetadata::toString ( ) const

Function "serializing" the stored information into a string.

This function translates the contents of the entire object into a single string.

The different parts of the configuration string are separated by "@" character. (So variable names and variable descriptions can't have this character in them.)

Returns: The configuration of this object "serialized" into a string

Definition at line 250 of file ObjectMetadata.cxx.

                                            {
 
      // Save the simple part of the information
      std::string result =
        std::to_string( SERIALIZER_VERSION ) +
         STRING_SEPARATOR + m_prefix +
         STRING_SEPARATOR + ( m_container ? "1" : "0" );
 
      // Save the serialized version of all the variables:
      std::set< Variable >::const_iterator itr = m_variables.begin();
      std::set< Variable >::const_iterator end = m_variables.end();
      for( ; itr != end; ++itr ) {
         result += STRING_SEPARATOR + itr->toString();
      }
 
      return result;
   }

◆ variables()

const std::set< ObjectMetadata::Variable > & D3PD::ObjectMetadata::variables ( ) const

Function for accessing all the variables of the D3PDObject.

Definition at line 578 of file ObjectMetadata.cxx.

                                                                           {
 
      return m_variables;
   }

Member Data Documentation

◆ m_container

bool D3PD::ObjectMetadata::m_container

protected

The D3PDObject describes a container.

Definition at line 175 of file ObjectMetadata.h.

◆ m_name

std::string D3PD::ObjectMetadata::m_name

protected

Name of the D3PDObject that this object describes.

Definition at line 173 of file ObjectMetadata.h.

◆ m_prefix

std::string D3PD::ObjectMetadata::m_prefix

protected

Prefix used by the D3PDObject.

Definition at line 174 of file ObjectMetadata.h.

◆ m_variables

std::set< Variable > D3PD::ObjectMetadata::m_variables

protected

The list of variables created by a D3PDObject.

Definition at line 172 of file ObjectMetadata.h.

◆ RANDOM_NAME_POSTFIX_LENGTH

const size_t D3PD::ObjectMetadata::RANDOM_NAME_POSTFIX_LENGTH = 6

static

Length of the random string appended to the object name.

Definition at line 109 of file ObjectMetadata.h.

◆ SERIALIZER_VERSION

const unsigned int D3PD::ObjectMetadata::SERIALIZER_VERSION = 1

static

"Version number" of the serialized information

While I don't plan to change this class any time soon, we should be able to clearly decide later on if the format of the metadata serialization changed, which version was used to write the metadata found in a given file.

Definition at line 119 of file ObjectMetadata.h.

◆ STRING_SEPARATOR

const char *const D3PD::ObjectMetadata::STRING_SEPARATOR = "@"

static

Character separating parts of the object's metadata.

Definition at line 111 of file ObjectMetadata.h.

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

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Attributes

Static Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ObjectMetadata() [1/2]

◆ ObjectMetadata() [2/2]

Member Function Documentation

◆ addDimensionedVariable() [1/3]

◆ addDimensionedVariable() [2/3]

◆ addDimensionedVariable() [3/3]

◆ addVariable() [1/3]

◆ addVariable() [2/3]

◆ addVariable() [3/3]

◆ ATLAS_NOT_THREAD_SAFE() [1/2]

◆ ATLAS_NOT_THREAD_SAFE() [2/2]

◆ clear()

◆ container()

◆ merge()

◆ name()

◆ objectName()

◆ operator+=()

◆ operator<()

◆ operator=()

◆ operator==()

◆ prefix()

◆ read()

◆ setContainer()

◆ setName()

◆ setPrefix()

◆ toString()

◆ variables()

Member Data Documentation

◆ m_container

◆ m_name

◆ m_prefix

◆ m_variables

◆ RANDOM_NAME_POSTFIX_LENGTH

◆ SERIALIZER_VERSION

◆ STRING_SEPARATOR