a base class that manages a set of files belonging to a particular data set and the associated meta-data. More...

#include <Sample.h>

Inheritance diagram for SH::Sample:

Collaboration diagram for SH::Sample:

Public Member Functions
void	testInvariant () const
	test the invariant of this object More...

virtual	~Sample ()
	standard destructor More...

const std::string &	name () const
	the name of the sample we are using More...

void	name (std::string val_name)
	set the value of name More...

std::size_t	numFiles () const
	the number of files in the sample More...

std::string	fileName (std::size_t index) const
	the name of the file with the given index More...

SamplePtr	makeLocal () const
	Make this a local sample, i.e. More...

const TagList &	tags () const
	the tag list we are using More...

void	tags (const TagList &tags)
	set the content of tags() More...

void	addTag (const std::string &tag)
	add a tag to the content of tags() More...

void	updateLocation (const std::string &from, const std::string &to)
	update all file references starting with from to to More...

MetaObject *	meta ()
	the meta-information for this sample More...

const MetaObject *	meta () const
	the meta-information for this sample More...

std::vector< std::string >	makeFileList () const
	make a list of all files, prestaging them if necessary More...

TChain *	makeTChain () const
	create a TChain object, containing all these files More...

TObject *	readHist (const std::string &name) const
	read an object from a histogram file More...

bool	contains (const std::string &name) const
	whether this sample contains a sample of the given name More...

void	addSamples (SampleHandler &result)
	add all samples this sample corresponds to to the given sample handler More...

void	print () const
	print the debugging output to the screen More...

void	printContent () const
	print the debugging output to the screen More...

Long64_t	getNumEntries () const
	get the number of entries More...

TCollection *	metaDataList ()
	get the meta-data list More...

const TCollection *	metaDataList () const
	get the meta-data list More...

void	removeMeta (const std::string &name)
	remove all meta-information with the given name More...

void	addReplaceMeta (TNamed *meta_swallow)
	add a meta-data object and remove any existing meta-data with the same name More...

TObject *	getMeta (const std::string &name)
	the meta-data object with the given name More...

const TObject *	getMeta (const std::string &name) const
	the meta-data object with the given name More...

double	getMetaDouble (const std::string &name, double def_val=0) const
	the meta-data double with the given name More...

std::string	getMetaString (const std::string &name, const std::string &def_val="") const
	the meta-data string with the given name More...

void	setMetaDouble (const std::string &name, double value)
	set the meta-data double with the given name More...

void	setMetaString (const std::string &name, const std::string &value)
	set the meta-data string with the given name More...

void	fetchMeta (const Sample &source)
	fetch the meta-data from the given sample. More...

Protected Member Functions
	Sample (const std::string &name)
	standard constructor More...

virtual std::size_t	getNumFiles () const =0
	the number of files in the sample More...

virtual std::string	getFileName (std::size_t index) const =0
	the name of the file with the given index More...

virtual SamplePtr	doMakeLocal () const =0
	Make this a local sample, i.e. More...

virtual std::vector< std::string >	doMakeFileList () const =0
	make a list of all files, prestaging them if necessary More...

virtual void	doUpdateLocation (const std::string &from, const std::string &to)
	update all file references starting with from to to More...

virtual TObject *	doReadHist (const std::string &name) const
	read an object from a histogram file More...

virtual bool	getContains (const std::string &name) const
	whether this sample contains a sample of the given name More...

virtual void	doAddSamples (SampleHandler &result)
	add all samples this sample corresponds to to the given sample handler More...

Private Member Functions
void	alloc () const
	increase the reference count by one More...

void	release () const
	decrease the reference count by one More...

	Sample (const Sample &that)

Sample &	operator= (const Sample &that)

	ClassDef (Sample, 2)

Private Attributes
std::string	m_name
	the name of the sample we are using More...

TagList	m_tags
	the tag list we are using More...

MetaObject *	m_meta
	the meta-information for this sample More...

std::atomic< unsigned >	m_references
	the reference count More...

Friends
class	SamplePtr

Related Functions
(Note that these are not member functions.)
std::string	dbg (const Sample &obj, unsigned verbosity=0)
	the debugging info of this object More...

Detailed Description

a base class that manages a set of files belonging to a particular data set and the associated meta-data.

While for most people this is essentially just a fancy file list, it hides a lot of flexibility. Besides a simple file list, this could also be a sample on the grid, or on tape storage that first needs to be pre-staged before it can be used.

Definition at line 53 of file Sample.h.

Constructor & Destructor Documentation

◆ ~Sample()

virtual SH::Sample::~Sample ( )

virtual

standard destructor

Guarantee: no-fail

◆ Sample() [1/2]

SH::Sample::Sample ( const std::string & name )

protected

standard constructor

Guarantee: strong

Failures: low level errors II

◆ Sample() [2/2]

SH::Sample::Sample ( const Sample & that )

private

Rationale: hiding this to avoid slicing

Member Function Documentation

◆ addReplaceMeta()

void SH::Sample::addReplaceMeta ( TNamed * meta_swallow )

add a meta-data object and remove any existing meta-data with the same name

Parameters

meta_swallow the meta-object to add

Precondition: meta_swallow != 0

Guarantee: basic, may delete some entries without adding the new one

Failures: out of memory II

◆ addSamples()

void SH::Sample::addSamples ( SampleHandler & result )

add all samples this sample corresponds to to the given sample handler

Guarantee: basic, may only add some

Failures: out of memory II

Rationale this is used with composite samples to find the: actual list of samples to run on.

◆ addTag()

void SH::Sample::addTag ( const std::string & tag )

add a tag to the content of tags()

Guarantee: strong

Failures: out of memory II

◆ alloc()

void SH::Sample::alloc ( ) const

private

increase the reference count by one

Guarantee: no-fail

◆ ClassDef()

SH::Sample::ClassDef	(	Sample	,
		2
	)

private

◆ contains()

bool SH::Sample::contains ( const std::string & name ) const

whether this sample contains a sample of the given name

Returns: whether this sample contains a sample of the given name (or whether the sample itself has the given name)

Guarantee: no-fail

Rationale: this is used with composite sample to make sure we don't create ring like structures that would lead to endless recursion. the reason to check by name, not by address is that we will probably want to add these samples to a sample handler at some point.

◆ doAddSamples()

virtual void SH::Sample::doAddSamples ( SampleHandler & result )

protectedvirtual

add all samples this sample corresponds to to the given sample handler

Guarantee: basic, may only add some

Failures: out of memory II

Rationale this is used with composite samples to find the: actual list of samples to run on.

Rationale: the virtual part of SH::Sample::addSamples()

Reimplemented in SH::SampleComposite.

◆ doMakeFileList()

virtual std::vector<std::string> SH::Sample::doMakeFileList ( ) const

protectedpure virtual

make a list of all files, prestaging them if necessary

Guarantee: basic

Failures: out of memory III
file catalogue failures
prestaging failures

Rationale: the virtual part of Sample::makeFileList

Implemented in SH::SampleLocal, SH::SampleGrid, SH::SampleComposite, SH::SampleHist, and SH::SampleMeta.

◆ doMakeLocal()

virtual SamplePtr SH::Sample::doMakeLocal ( ) const

protectedpure virtual

Make this a local sample, i.e.

one which can be directly opened with TFile::Open

Returns: the local sample, or "this" if this already is a local sample

Guarantee: strong

Failures: out of memory III
can not make local sample

Rationale: the virtual part of SH::Sample::makeLocal()

Implemented in SH::SampleLocal, SH::SampleGrid, SH::SampleComposite, SH::SampleHist, and SH::SampleMeta.

◆ doReadHist()

virtual TObject* SH::Sample::doReadHist ( const std::string & name ) const

protectedvirtual

read an object from a histogram file

Returns: the object read or NULL if it was not found

Guarantee: strong

Failures: out of memory II
i/o errors

Rationale: the virtual part of SH::Sample::readHist()

Reimplemented in SH::SampleHist.

◆ doUpdateLocation()

virtual void SH::Sample::doUpdateLocation	(	const std::string &	from,
		const std::string &	to
	)

protectedvirtual

update all file references starting with from to to

Parameters

from	the original path to the data area
to	the new path to the data area

Guarantee: basic, may update partially

Failures: out of memory II

Precondition: !from.empty()

Postcondition: !to.empty()

Rationale: this is needed when moving data around without recreating the samples from scratch

Rationale: the virtual part of SH::Sample::updateLocation()

Reimplemented in SH::SampleLocal, SH::SampleComposite, and SH::SampleHist.

◆ fetchMeta()

void SH::Sample::fetchMeta ( const Sample & source )

fetch the meta-data from the given sample.

fields that have a name that starts with "nc_" are not copied.

Guarantee: basic, may only fetch some meta-data

Failures: out of memory II

Rationale this is used by EventLoop, to copy the: meta-data from the input samples to the output samples. the prefix "nc_" is used to indicate meta-data entries that only apply to the current sample, or are options to the specific EventLoop job.

◆ fileName()

std::string SH::Sample::fileName ( std::size_t index ) const

the name of the file with the given index

Parameters

index the index of the file

Guarantee: no-fail

Precondition: index < numFiles()

Postcondition: !result.empty()

Warning: this is meant more for debugging and may or may not do what you want, e.g. if this is a grid dataset the file may not be directly accessible.

◆ getContains()

virtual bool SH::Sample::getContains ( const std::string & name ) const

protectedvirtual

whether this sample contains a sample of the given name

Returns: whether this sample contains a sample of the given name (or whether the sample itself has the given name)

Guarantee: no-fail

Rationale: this is used with composite sample to make sure we don't create ring like structures that would lead to endless recursion. the reason to check by name, not by address is that we will probably want to add these samples to a sample handler at some point.

Rationale: the virtual part of SH::Sample::contains()

Reimplemented in SH::SampleComposite.

◆ getFileName()

virtual std::string SH::Sample::getFileName ( std::size_t index ) const

protectedpure virtual

the name of the file with the given index

Parameters

index the index of the file

Guarantee: no-fail

Precondition: index < numFiles()

Postcondition: !result.empty()

Warning: this is meant more for debugging and may or may not do what you want, e.g. if this is a grid dataset the file may not be directly accessible.

Rationale: the virtual part of Sample::fileName()

Implemented in SH::SampleLocal, SH::SampleGrid, SH::SampleComposite, SH::SampleHist, and SH::SampleMeta.

◆ getMeta() [1/2]

TObject* SH::Sample::getMeta ( const std::string & name )

the meta-data object with the given name

Returns: the meta-data object with the given name, or NULL if there is no such entry

Parameters

name	the name of the meta-data object

Guarantee: no-fail

◆ getMeta() [2/2]

const TObject* SH::Sample::getMeta ( const std::string & name ) const

the meta-data object with the given name

Returns: the meta-data object with the given name, or NULL if there is no such entry

Parameters

name	the name of the meta-data object

Guarantee: no-fail

◆ getMetaDouble()

double SH::Sample::getMetaDouble	(	const std::string &	name,
		double	def_val = `0`
	)		const

the meta-data double with the given name

Returns: the meta-data with the given name, or def_value if that meta-data is not available or does not have the right type

Parameters

name	the name of the meta-data object
dev_val	the value to return if no meta-data object of the given name exists, or if it does not have the right type

Guarantee: no-fail

◆ getMetaString()

std::string SH::Sample::getMetaString	(	const std::string &	name,
		const std::string &	def_val = `""`
	)		const

the meta-data string with the given name

Returns: the meta-data with the given name, or def_value if that meta-data is not available or does not have the right type

Parameters

name	the name of the meta-data object
dev_val	the value to return if no meta-data object of the given name exists, or if it does not have the right type

Guarantee: no-fail

Rationale: I return the string by value, because returning by reference seems to break the python binding.

◆ getNumEntries()

Long64_t SH::Sample::getNumEntries ( ) const

get the number of entries

Guarantee: strong

Failures: i/o errors

◆ getNumFiles()

virtual std::size_t SH::Sample::getNumFiles ( ) const

protectedpure virtual

the number of files in the sample

Guarantee: no-fail

Rationale: the virtual part of Sample::numFiles()

Implemented in SH::SampleLocal, SH::SampleGrid, SH::SampleComposite, SH::SampleHist, and SH::SampleMeta.

◆ makeFileList()

std::vector<std::string> SH::Sample::makeFileList ( ) const

make a list of all files, prestaging them if necessary

Guarantee: basic

Failures: out of memory III
file catalogue failures
prestaging failures

◆ makeLocal()

SamplePtr SH::Sample::makeLocal ( ) const

Make this a local sample, i.e.

one which can be directly opened with TFile::Open

Returns: the local sample, or "this" if this already is a local sample

Guarantee: strong

Failures: out of memory III
can not make local sample

◆ makeTChain()

TChain* SH::Sample::makeTChain ( ) const

create a TChain object, containing all these files

Guarantee: strong

Failures: out of memory II
chain making not supported

Postcondition: result != 0

◆ meta() [1/2]

MetaObject* SH::Sample::meta ( )

the meta-information for this sample

Guarantee: no-fail

Invariant: meta != 0

◆ meta() [2/2]

const MetaObject* SH::Sample::meta ( ) const

the meta-information for this sample

Guarantee: no-fail

Invariant: meta != 0

◆ metaDataList() [1/2]

TCollection* SH::Sample::metaDataList ( )

get the meta-data list

Guarantee: no-fail

Postcondition: result != 0

Deprecated:: use meta() instead, or (preferably) access of meta-data by name

◆ metaDataList() [2/2]

const TCollection* SH::Sample::metaDataList ( ) const

get the meta-data list

Guarantee: no-fail

Postcondition: result != 0

Deprecated:: use meta() instead, or (preferably) access of meta-data by name

◆ name() [1/2]

const std::string& SH::Sample::name ( ) const

the name of the sample we are using

Guarantee: no-fail

◆ name() [2/2]

void SH::Sample::name ( std::string val_name )

set the value of name

Guarantee: no-fail / strong

Failures: out of memory II

Failures: Sample already owned by SampleHandler

Rationale: setting the sample name can be beneficial, if the sample auto-discovery set a duplicate (or otherwise unsuitable) name.

Warning: this must be done before adding it to the SampleHandler, or alternatively a clone must be made that can then be added to a new SampleHandler.

◆ numFiles()

std::size_t SH::Sample::numFiles ( ) const

the number of files in the sample

Guarantee: no-fail

◆ operator=()

Sample& SH::Sample::operator= ( const Sample & that )

private

Rationale: hiding this to avoid slicing

◆ print()

void SH::Sample::print ( ) const

print the debugging output to the screen

Guarantee: basic, may print partially

Failures: out of memory II

Failures: stream errors

◆ printContent()

void SH::Sample::printContent ( ) const

print the debugging output to the screen

Guarantee: basic, may print partially

Failures: out of memory II

Failures: stream errors

Rationale: added a second print method for python where print is a keyword

◆ readHist()

TObject* SH::Sample::readHist ( const std::string & name ) const

read an object from a histogram file

Returns: the object read or NULL if it was not found

Guarantee: strong

Failures: out of memory II
i/o errors

◆ release()

void SH::Sample::release ( ) const

private

decrease the reference count by one

Side Effects: release this sample if that was the last reference

Guarantee: no-fail

Precondition: reference count > 0

◆ removeMeta()

void SH::Sample::removeMeta ( const std::string & name )

remove all meta-information with the given name

Parameters

name	the meta-data name to remove

Guarantee: basic, may only delete some entries

Failures: out of memory II

◆ setMetaDouble()

void SH::Sample::setMetaDouble	(	const std::string &	name,
		double	value
	)

set the meta-data double with the given name

Parameters

name	the name of the meta-data
value	the value to which it is set

Guarantee: basic, may clear old entry without adding new one

Failures: out of memory II

◆ setMetaString()

void SH::Sample::setMetaString	(	const std::string &	name,
		const std::string &	value
	)

set the meta-data string with the given name

Parameters

name	the name of the meta-data
value	the value to which it is set

Guarantee: basic, may clear old entry without adding new one

Failures: out of memory II

◆ tags() [1/2]

const TagList& SH::Sample::tags ( ) const

the tag list we are using

Guarantee: no-fail

◆ tags() [2/2]

void SH::Sample::tags ( const TagList & tags )

set the content of tags()

Guarantee: strong

Failures: out of memory II

◆ testInvariant()

void SH::Sample::testInvariant ( ) const

test the invariant of this object

Guarantee: no-fail

◆ updateLocation()

void SH::Sample::updateLocation	(	const std::string &	from,
		const std::string &	to
	)

update all file references starting with from to to

Parameters

from	the original path to the data area
to	the new path to the data area

Guarantee: basic, may update partially

Failures: out of memory II

Precondition: !from.empty()

Postcondition: !to.empty()

Rationale: this is needed when moving data around without recreating the samples from scratch

Friends And Related Function Documentation

◆ dbg()

std::string dbg	(	const Sample &	obj,
		unsigned	verbosity = `0`
	)

Returns: a string representation of the object content

Parameters

obj	the object to be presented
verbosity	the level of verbosity (higher number -> more information)

Guarantee: strong

Failures: out of memory II

◆ SamplePtr

friend class SamplePtr

friend

Definition at line 448 of file Sample.h.

Member Data Documentation

◆ m_meta

MetaObject* SH::Sample::m_meta

private

the meta-information for this sample

See also: meta

Definition at line 483 of file Sample.h.

◆ m_name

std::string SH::Sample::m_name

private

the name of the sample we are using

See also: name

Definition at line 475 of file Sample.h.

◆ m_references

std::atomic<unsigned> SH::Sample::m_references

mutableprivate

the reference count

Definition at line 487 of file Sample.h.

◆ m_tags

TagList SH::Sample::m_tags

private

the tag list we are using

See also: tags

Definition at line 479 of file Sample.h.

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

Sample.h

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Sample()

◆ Sample() [1/2]

◆ Sample() [2/2]

Member Function Documentation

◆ addReplaceMeta()

◆ addSamples()

◆ addTag()

◆ alloc()

◆ ClassDef()

◆ contains()

◆ doAddSamples()

◆ doMakeFileList()

◆ doMakeLocal()

◆ doReadHist()

◆ doUpdateLocation()

◆ fetchMeta()

◆ fileName()

◆ getContains()

◆ getFileName()

◆ getMeta() [1/2]

◆ getMeta() [2/2]

◆ getMetaDouble()

◆ getMetaString()

◆ getNumEntries()

◆ getNumFiles()

◆ makeFileList()

◆ makeLocal()

◆ makeTChain()

◆ meta() [1/2]

◆ meta() [2/2]

◆ metaDataList() [1/2]

◆ metaDataList() [2/2]

◆ name() [1/2]

◆ name() [2/2]

◆ numFiles()

◆ operator=()

◆ print()

◆ printContent()

◆ readHist()

◆ release()

◆ removeMeta()

◆ setMetaDouble()

◆ setMetaString()

◆ tags() [1/2]

◆ tags() [2/2]

◆ testInvariant()

◆ updateLocation()

Friends And Related Function Documentation

◆ dbg()

◆ SamplePtr

Member Data Documentation

◆ m_meta

◆ m_name

◆ m_references

◆ m_tags