#include <FlatObject.h>

Inherited by o2::gpu::NDPiecewisePolynomials< FDim, FDegree, false >, o2::gpu::Spline1DContainerBase< DataT, FlatObject >, o2::gpu::Spline2DContainerBase< DataT, FlatObject >, o2::base::MatLayerCyl, o2::base::MatLayerCylSet, o2::gpu::IrregularSpline1D, o2::gpu::IrregularSpline2D3D, o2::gpu::MultivariatePolynomial< Dim, Degree, InteractionOnly >, o2::gpu::NDPiecewisePolynomials< Dim, Degree, InteractionOnly >, o2::gpu::SemiregularSpline2D3D, o2::gpu::Spline1DContainerBase< DataT, FlatBase >, o2::gpu::Spline2DContainerBase< DataT, FlatBase >, o2::gpu::SplineContainer< DataT >, o2::gpu::TPCFastSpaceChargeCorrection, o2::gpu::TPCFastTransform, o2::tpc::CalibdEdxContainer, o2::tpc::CalibdEdxTrackTopologyPol, o2::tpc::CalibdEdxTrackTopologySpline, and o2::trd::GeometryFlat.

Public Member Functions
	FlatObject ()=default
	_____________ Constructors / destructors __________________________

	~FlatObject ()

	FlatObject (const FlatObject &)=delete

FlatObject &	operator= (const FlatObject &)=delete

template<typename T >
T *	resizeArray (T &ptr, int32_t oldSize, int32_t newSize, T newPtr=nullptr)

template<typename T >
T **	resizeArray (T &ptr, int32_t oldSize, int32_t newSize, T newPtr=nullptr)

void	destroy ()
	_______________ Utilities _______________________________________________

	GPUdi () size_t getFlatBufferSize() const
	Gives size of the flat buffer.

	GPUdi () const char *getFlatBufferPtr() const
	Gives pointer to the flat buffer.

bool	isConstructed () const
	Tells if the object is constructed.

bool	isBufferInternal () const
	Tells if the buffer is internal.

void	adoptInternalBuffer (char *buf)

void	clearInternalBufferPtr ()

void	printC () const
	Print the content of the flat buffer.

Static Public Member Functions
static constexpr size_t	alignSize (size_t sizeBytes, size_t alignmentBytes)
	_______________ Generic utilities _______________________________________________

template<class T >
static T *	relocatePointer (const char oldBase, char newBase, const T *ptr)
	Relocates a pointer inside a buffer to the new buffer address.

template<class T , class TFile >
static int32_t	writeToFile (T &obj, TFile &outf, const char *name)
	write a child class object to the file

template<class T , class TFile >
static T *	readFromFile (TFile &inpf, const char *name)
	read a child class object from the file

template<class T >
static std::string	stressTest (T &obj)
	Test the flat object functionality for a child class T.

Protected Types
enum	ConstructionState : uint32_t { NotConstructed = 0x0 , Constructed = 0x1 , InProgress = 0x2 }
	GPUCA_GPUCODE. More...

Protected Member Functions
void	startConstruction ()
	_____________ Construction _________

void	finishConstruction (int32_t flatBufferSize)

void	cloneFromObject (const FlatObject &obj, char *newFlatBufferPtr)

char *	releaseInternalBuffer ()
	_____________ Methods for making the data buffer external __________________________

void	moveBufferTo (char *newBufferPtr)

void	setActualBufferAddress (char *actualFlatBufferPtr)
	_____________ Methods for moving the class with its external buffer to another location __________________________

void	setFutureBufferAddress (char *futureFlatBufferPtr)

	ClassDefNV (FlatObject, 1)
	Pointer to the flat buffer.

Static Protected Member Functions
static constexpr size_t	getClassAlignmentBytes ()
	GPUCA_GPUCODE.

static constexpr size_t	getBufferAlignmentBytes ()
	Gives minimal alignment in bytes required for the flat buffer.

Protected Attributes
int32_t	mFlatBufferSize = 0
	size of the flat buffer

uint32_t	mConstructionMask = ConstructionState::NotConstructed
	mask for constructed object members, first two bytes are used by this class

char *	mFlatBufferContainer = nullptr

char *	mFlatBufferPtr = nullptr

Detailed Description

The FlatObject class represents base class for flat objects. Objects may contain variable-size data, stored in a buffer. The data may contain pointers to the buffer inside. The buffer can be internal, placed in mFlatBufferContainer, or external.

Important: All methods of the FlatObject are marked "protected" in order to not let users to call them directly. They all should be reimplemented in daughter classes, because only daughter class knows how to reset all pointers in the data buffer. This is an unusual decision. Normally, to avoid confusion one should just mark methods of a base class virtual or abstract. But this right solution invokes use of a virtual table and complicates porting objects to other machines. Therefore: no virtual functions but protected methods.

== Object construction.

This base class performs some basic operations, like setting initialisation flags, allocating / releasing memory etc. As no virtual methods are involved, the rest should be done manually in daughter classes.

It is assumed, that a daughter object may be complicated and can not be constructed by just a call of its c++ constructor. May be it needs to wait for something else to be initialized first. Like a database or so.

Therefore the object may find itself in some intermediate half-constructed state, where its data stays in private temporary arrays and can not be yet copied to the flat buffer.

To deal with it, some extra control on the initialization flow is provided.

The object can be constructed either a) by calling void startConstruction(); ... do something .. void finishConstruction( int32_t flatBufferSize );

b) or by cloning from another constructed(!) object: obj.CloneFromObject(..)

A new obect is by default in "Not Constructed" state, operations with its buffer will cause an error.

== Making an internal buffer external option a) std::unique_ptr<char[]> p = obj.releaseInternalBuffer(); ..taking care on p..

option b) std::unique_ptr<char[]> p( new char[obj.GetBufferSize()] ); obj.moveBufferTo( p.get() ); ..taking care on p..

option c) std::unique_ptr<char[]> p( new char[obj.GetBufferSize()] ); obj.cloneFromObject(obj, p.get() ); ..taking care on p..

=== Making an external buffer internal

option a) obj.cloneFromObject( obj, nullptr );

option b) obj.moveBufferTo( nullptr );

== Moving an object to other machine.

This only works when the buffer is external. The object and its buffer are supposed to be bit-wise ported to a new place. And they need to find each other there. There are 2 options:

option a) The new buffer location is only known after the transport. In this case call: obj.setActualBufferAddress( new buffer address ) from the new place.

option b) The new buffer location is known before the transport (case of porting to GPU). In this case call: obj.setFutureBufferAddress( char* futureFlatBufferPtr ); before the transport. The object will be ready-to-use right after the porting.

Definition at line 118 of file FlatObject.h.

Member Enumeration Documentation

◆ ConstructionState

enum o2::gpu::FlatObject::ConstructionState : uint32_t

protected

GPUCA_GPUCODE.

_______________ Data members _______________________________________________ Enumeration of construction states

Enumerator
NotConstructed	the object is not constructed
Constructed	the object is constructed, temporary memory is released
InProgress	construction started: temporary memory is reserved

Definition at line 314 of file FlatObject.h.

Constructor & Destructor Documentation

◆ FlatObject() [1/2]

o2::gpu::FlatObject::FlatObject ( )

default

_____________ Constructors / destructors __________________________

Default constructor / destructor

◆ ~FlatObject()

o2::gpu::FlatObject::~FlatObject ( )

inline

========================================================================================================

  Inline implementations of methods

========================================================================================================

Definition at line 349 of file FlatObject.h.

◆ FlatObject() [2/2]

o2::gpu::FlatObject::FlatObject ( const FlatObject & )

delete

Member Function Documentation

◆ adoptInternalBuffer()

void o2::gpu::FlatObject::adoptInternalBuffer ( char * buf )

inline

Definition at line 546 of file FlatObject.h.

◆ alignSize()

static constexpr size_t o2::gpu::FlatObject::alignSize	(	size_t	sizeBytes,
		size_t	alignmentBytes
	)

inlinestaticconstexpr

_______________ Generic utilities _______________________________________________

Increases given size to achieve required alignment

Definition at line 275 of file FlatObject.h.

◆ ClassDefNV()

o2::gpu::FlatObject::ClassDefNV	(	FlatObject	,
		1
	)

protected

Pointer to the flat buffer.

◆ clearInternalBufferPtr()

void o2::gpu::FlatObject::clearInternalBufferPtr ( )

inline

Definition at line 553 of file FlatObject.h.

◆ cloneFromObject()

void o2::gpu::FlatObject::cloneFromObject	(	const FlatObject &	obj,
		char *	newFlatBufferPtr
	)

inlineprotected

Initializes from another object, copies data to newBufferPtr When newBufferPtr==nullptr, an internal container will be created, the data will be copied there. A daughter class should relocate pointers inside the buffer.

Initializes from another object, copies data to newBufferPtr When newBufferPtr==nullptr, the internal container will be created, the data will be copied there. obj can be *this (provided it does not own its buffer AND the external buffer is provided, which means

Definition at line 385 of file FlatObject.h.

◆ destroy()

void o2::gpu::FlatObject::destroy ( )

inline

_______________ Utilities _______________________________________________

Set the object to NotConstructed state, release the buffer

Definition at line 361 of file FlatObject.h.

◆ finishConstruction()

void o2::gpu::FlatObject::finishConstruction ( int32_t flatBufferSize )

inlineprotected

Finishes construction: creates internal flat buffer. A daughter class should put all created variable-size members to this buffer

Definition at line 370 of file FlatObject.h.

◆ getBufferAlignmentBytes()

static constexpr size_t o2::gpu::FlatObject::getBufferAlignmentBytes ( )

inlinestaticconstexprprotected

Gives minimal alignment in bytes required for the flat buffer.

Definition at line 195 of file FlatObject.h.

◆ getClassAlignmentBytes()

static constexpr size_t o2::gpu::FlatObject::getClassAlignmentBytes ( )

inlinestaticconstexprprotected

GPUCA_GPUCODE.

_____________ Memory alignment __________________________ Gives minimal alignment in bytes required for the class object

Definition at line 192 of file FlatObject.h.

◆ GPUdi() [1/2]

o2::gpu::FlatObject::GPUdi ( ) const

inline

Gives pointer to the flat buffer.

Definition at line 257 of file FlatObject.h.

◆ GPUdi() [2/2]

o2::gpu::FlatObject::GPUdi ( ) const

inline

Gives size of the flat buffer.

Definition at line 254 of file FlatObject.h.

◆ isBufferInternal()

bool o2::gpu::FlatObject::isBufferInternal ( ) const

inline

Tells if the buffer is internal.

Definition at line 263 of file FlatObject.h.

◆ isConstructed()

bool o2::gpu::FlatObject::isConstructed ( ) const

inline

Tells if the object is constructed.

Definition at line 260 of file FlatObject.h.

◆ moveBufferTo()

void o2::gpu::FlatObject::moveBufferTo ( char * newBufferPtr )

inlineprotected

Sets buffer pointer to the new address, move the buffer content there. A daughter class must relocate all the pointers inside th buffer

sets buffer pointer to the new address, move the buffer content there.

Definition at line 408 of file FlatObject.h.

◆ operator=()

FlatObject & o2::gpu::FlatObject::operator= ( const FlatObject & )

delete

◆ printC()

void o2::gpu::FlatObject::printC ( ) const

inline

Print the content of the flat buffer.

Print the content of the flat buffer

Definition at line 470 of file FlatObject.h.

◆ readFromFile()

template<class T , class TFile >

T * o2::gpu::FlatObject::readFromFile	(	TFile &	inpf,
		const char *	name
	)

inlinestatic

read a child class object from the file

read from file

Definition at line 514 of file FlatObject.h.

◆ releaseInternalBuffer()

char * o2::gpu::FlatObject::releaseInternalBuffer ( )

inlineprotected

_____________ Methods for making the data buffer external __________________________

Definition at line 538 of file FlatObject.h.

◆ relocatePointer()

template<class T >

static T * o2::gpu::FlatObject::relocatePointer	(	const char *	oldBase,
		char *	newBase,
		const T *	ptr
	)

inlinestatic

Relocates a pointer inside a buffer to the new buffer address.

Definition at line 283 of file FlatObject.h.

◆ resizeArray() [1/2]

template<typename T >

T * o2::gpu::FlatObject::resizeArray	(	T *&	ptr,
		int32_t	oldSize,
		int32_t	newSize,
		T *	newPtr = `nullptr`
	)

inline

Definition at line 135 of file FlatObject.h.

◆ resizeArray() [2/2]

template<typename T >

T ** o2::gpu::FlatObject::resizeArray	(	T **&	ptr,
		int32_t	oldSize,
		int32_t	newSize,
		T **	newPtr = `nullptr`
	)

inline

Definition at line 163 of file FlatObject.h.

◆ setActualBufferAddress()

void o2::gpu::FlatObject::setActualBufferAddress ( char * actualFlatBufferPtr )

inlineprotected

_____________ Methods for moving the class with its external buffer to another location __________________________

Sets the actual location of the flat buffer after it has been moved (i.e. to another maschine) It sets mFlatBufferPtr to actualFlatBufferPtr. A daughter class should later update all the pointers inside the buffer to the new location.

Sets the actual location of the external flat buffer after it has been moved (i.e. to another maschine)

It sets mFlatBufferPtr to actualFlatBufferPtr. A daughter class should update all the pointers inside the buffer in the new location.

Definition at line 559 of file FlatObject.h.

◆ setFutureBufferAddress()

void o2::gpu::FlatObject::setFutureBufferAddress ( char * futureFlatBufferPtr )

inlineprotected

Sets a future location of the external flat buffer before moving it to this location (i.e. when copying to GPU).

The object can be used immidiatelly after the move, call of setActualFlatBufferAddress() is not needed.

A daughter class should already relocate all the pointers inside the current buffer to the future location. It should not touch memory in the future location, since it may be not yet available.

!!! Information about the actual buffer location will be lost. !!! Most of the class methods may be called only after the buffer will be moved to its new location. !!! To undo call setActualFlatBufferAddress()

Sets a future location of the external flat buffer before moving it to this location.

A daughter class should already reset all the pointers inside the current buffer to the future location without touching memory in the future location.

Definition at line 569 of file FlatObject.h.

◆ startConstruction()

void o2::gpu::FlatObject::startConstruction ( )

inlineprotected

_____________ Construction _________

Starts the construction procedure. A daughter class should reserve temporary memory.

Definition at line 354 of file FlatObject.h.

◆ stressTest()

template<class T >

std::string o2::gpu::FlatObject::stressTest ( T & obj )

inlinestatic

Test the flat object functionality for a child class T.

Test the flat object functionality for an object of a child class T the obj is modified here. Check if it is functional after the test.

Definition at line 423 of file FlatObject.h.

◆ writeToFile()

template<class T , class TFile >

int32_t o2::gpu::FlatObject::writeToFile	(	T &	obj,
		TFile &	outf,
		const char *	name
	)

inlinestatic

write a child class object to the file

store to file

Definition at line 492 of file FlatObject.h.

Member Data Documentation

◆ mConstructionMask

uint32_t o2::gpu::FlatObject::mConstructionMask = ConstructionState::NotConstructed

protected

mask for constructed object members, first two bytes are used by this class

Definition at line 321 of file FlatObject.h.

◆ mFlatBufferContainer

char* o2::gpu::FlatObject::mFlatBufferContainer = nullptr

protected

Definition at line 322 of file FlatObject.h.

◆ mFlatBufferPtr

char* o2::gpu::FlatObject::mFlatBufferPtr = nullptr

protected

Definition at line 323 of file FlatObject.h.

◆ mFlatBufferSize

int32_t o2::gpu::FlatObject::mFlatBufferSize = 0

protected

size of the flat buffer

Definition at line 320 of file FlatObject.h.

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

/home/runner/work/AliceO2/AliceO2/GPU/Utils/FlatObject.h

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ ConstructionState

Constructor & Destructor Documentation

◆ FlatObject() [1/2]

◆ ~FlatObject()

◆ FlatObject() [2/2]

Member Function Documentation

◆ adoptInternalBuffer()

◆ alignSize()

◆ ClassDefNV()

◆ clearInternalBufferPtr()

◆ cloneFromObject()

◆ destroy()

◆ finishConstruction()

◆ getBufferAlignmentBytes()

◆ getClassAlignmentBytes()

◆ GPUdi() [1/2]

◆ GPUdi() [2/2]

◆ isBufferInternal()

◆ isConstructed()

◆ moveBufferTo()

◆ operator=()

◆ printC()

◆ readFromFile()

◆ releaseInternalBuffer()

◆ relocatePointer()

◆ resizeArray() [1/2]

◆ resizeArray() [2/2]

◆ setActualBufferAddress()

◆ setFutureBufferAddress()

◆ startConstruction()

◆ stressTest()

◆ writeToFile()

Member Data Documentation

◆ mConstructionMask

◆ mFlatBufferContainer

◆ mFlatBufferPtr

◆ mFlatBufferSize