Base class that encapsulates common behavior of backend engines. More...

#include <engine.hpp>

Inheritance diagram for hebench::cpp::BaseEngine:

Collaboration diagram for hebench::cpp::BaseEngine:

Public Member Functions
	BaseEngine (const BaseEngine &)=delete

BaseEngine &	operator= (const BaseEngine &)=delete

	BaseEngine (BaseEngine &&)=delete

BaseEngine &	operator= (BaseEngine &&)=delete

	~BaseEngine () override

std::int64_t	classTag () const override
	Retrieves the tag of the class to which this object belongs. More...

std::string	getBenchmarkDescriptionEx (hebench::APIBridge::Handle h_bench_desc, const hebench::APIBridge::WorkloadParams *p_w_params) const
	Retrieves backend specific text description for a benchmark descriptor. More...

const std::unordered_map< hebench::APIBridge::Scheme, std::string > &	schemeName () const
	Retrieves a dictionary that maps schemes known to this benchmark to their human readable names. More...

const std::unordered_map< hebench::APIBridge::Security, std::string > &	securityName () const
	Retrieves a dictionary that maps security types known to this benchmark to their human readable names. More...

std::uint64_t	subscribeBenchmarkCount () const
	Retrieves the number of benchmarks for which the backend is registering to perform. More...

void	subscribeBenchmarks (hebench::APIBridge::Handle *p_h_bench_descs, std::uint64_t count) const
	Retrieves the benchmarks for which the backend is registering to perform. More...

std::uint64_t	getWorkloadParamsCount (hebench::APIBridge::Handle h_bench_desc) const
	Retrieves the number of workload parameters for the decribed benchmark. More...

std::uint64_t	getDefaultWorkloadParamsCount (hebench::APIBridge::Handle h_bench_desc) const
	Retrieves the number of sets of default arguments supported by this benchmark's workload. More...

void	describeBenchmark (hebench::APIBridge::Handle h_bench_desc, hebench::APIBridge::BenchmarkDescriptor p_bench_desc, hebench::APIBridge::WorkloadParams p_default_params, std::uint64_t default_count) const

hebench::APIBridge::Handle	createBenchmark (hebench::APIBridge::Handle h_bench_desc, const hebench::APIBridge::WorkloadParams *p_params)
	Creates the benchmark specified by the descriptor. More...

void	destroyBenchmark (hebench::APIBridge::Handle h_bench)
	Destroys and cleans up a benchmark created by createBenchmark(). More...

template<class T , typename... Args>
hebench::APIBridge::Handle	createHandle (std::uint64_t size, std::int64_t extra_tags, Args &&... args) const
	Encapsulates an object of type T in an opaque HEBench handle. More...

hebench::APIBridge::Handle	duplicateHandle (hebench::APIBridge::Handle h, std::int64_t new_tag, std::int64_t check_tags) const
	Duplicates a handle created by `createhandle()`. More...

hebench::APIBridge::Handle	duplicateHandle (hebench::APIBridge::Handle h, std::int64_t check_tags=0) const
	Duplicates a handle created by `createhandle()`. More...

template<class T , typename... Args>
T &	retrieveFromHandle (hebench::APIBridge::Handle h, std::int64_t extra_tags=0) const
	Retrieves the object of type T encapsulated in an opaque HEBench handle by method createHandle(). More...

template<class T , typename... Args>
EngineObject *	createEngineObj (Args &&... args) const
	Creates an `EngineObject` that wraps an object of type `T`. More...

template<class T , typename... Args>
std::shared_ptr< T >	createRAII (Args &&... args) const
	Creates a smart pointer of the specified template type. More...

template<class T , typename... Args>
T *	createObj (Args &&... args) const

template<class T >
void	destroyObj (T *p) const

Public Member Functions inherited from hebench::cpp::ITaggedObject
	ITaggedObject ()

virtual	~ITaggedObject ()

Static Public Member Functions
static const std::string &	getErrorDesc (hebench::APIBridge::ErrorCode err_code)
	Retrieves the description of a specific error code. More...

static hebench::APIBridge::ErrorCode	getLastError ()
	Retrieves the last error that occurred as set by setLastError(). More...

static const std::string &	getLastErrorDesc ()
	Retrieves the description of the last error that occurred as set by setLastError(). More...

static void	setLastError (hebench::APIBridge::ErrorCode value)
	Sets the last error code that occurred. More...

static void	setLastError (hebench::APIBridge::ErrorCode value, const std::string &err_desc)
	Sets the last error code that occurred. More...

Static Public Attributes
static constexpr std::int64_t	tag = 0x8000000000000000
	Used to identify this class when returned as a handle to Test Harness. More...

Static Public Attributes inherited from hebench::cpp::ITaggedObject
static constexpr std::int64_t	MaskByteSet = 0xFF

static constexpr std::int64_t	MaskReservedBits = MaskByteSet << 56
	Mask representing all bits reserved by C++ wrapper. More...

Protected Member Functions
	BaseEngine ()

virtual void	init ()=0
	Initializes the backend engine and populates the backend description. More...

std::shared_ptr< BenchmarkDescription >	matchBenchmark (hebench::APIBridge::Handle h_desc) const
	Retrieves the `BenchmarkDescription` object pointed by the specified handle. More...

void	addBenchmarkDescription (std::shared_ptr< BenchmarkDescription > p_desc)
	Adds a new benchmark to the list of benchmarks to register by this backend. More...

void	addSchemeName (hebench::APIBridge::Scheme scheme, const std::string &name)
	Adds a new supported scheme and name pair to the list of schemes supported by this backend. More...

void	addSecurityName (hebench::APIBridge::Security security, const std::string &name)
	Adds a new supported security and name pair to the list of securitty types supported by this backend. More...

Static Protected Member Functions
static void	addErrorCode (hebench::APIBridge::ErrorCode code, const std::string &description)
	Adds a new error code and the error description to the list of possible error codes that this backend can generate. More...

Detailed Description

Base class that encapsulates common behavior of backend engines.

Any backend engine must derive from this class in order to take advantage of the C++ wrapper boilerplate automation.

Definition at line 69 of file engine.hpp.

Constructor & Destructor Documentation

◆ BaseEngine() [1/3]

hebench::cpp::BaseEngine::BaseEngine ( const BaseEngine & )

delete

◆ BaseEngine() [2/3]

hebench::cpp::BaseEngine::BaseEngine ( BaseEngine && )

delete

◆ ~BaseEngine()

hebench::cpp::BaseEngine::~BaseEngine ( )

inlineoverride

Definition at line 88 of file engine.hpp.

◆ BaseEngine() [3/3]

hebench::cpp::BaseEngine::BaseEngine ( )

protected

Definition at line 30 of file engine.cpp.

Member Function Documentation

◆ addBenchmarkDescription()

void hebench::cpp::BaseEngine::addBenchmarkDescription ( std::shared_ptr< BenchmarkDescription > p_desc )

protected

Adds a new benchmark to the list of benchmarks to register by this backend.

Parameters

[in] p_desc Object describing the new benchmark.

This method is to be called during engine initialization.

See also: init()

Definition at line 67 of file engine.cpp.

◆ addErrorCode()

void hebench::cpp::BaseEngine::addErrorCode	(	hebench::APIBridge::ErrorCode	code,
		const std::string &	description
	)

staticprotected

Adds a new error code and the error description to the list of possible error codes that this backend can generate.

Parameters

[in]	code	Error code.
[in]	description	Description of the error as it will returned by hebench::APIBridge::getErrorDescription().

This method is to be called during engine initialization.

See also: init(), hebench::APIBridge::getErrorDescription()

Definition at line 72 of file engine.cpp.

◆ addSchemeName()

void hebench::cpp::BaseEngine::addSchemeName	(	hebench::APIBridge::Scheme	scheme,
		const std::string &	name
	)

protected

Adds a new supported scheme and name pair to the list of schemes supported by this backend.

Parameters

[in]	scheme	Scheme ID.
[in]	name	Corresponding name for the scheme.

This method is to be called during engine initialization.

See also: init(), hebench::APIBridge::getSchemeName()

Definition at line 80 of file engine.cpp.

◆ addSecurityName()

void hebench::cpp::BaseEngine::addSecurityName	(	hebench::APIBridge::Security	security,
		const std::string &	name
	)

protected

Adds a new supported security and name pair to the list of securitty types supported by this backend.

Parameters

[in]	security	Security ID.
[in]	name	Corresponding name for the new security type.

This method is to be called during engine initialization.

See also: init(), hebench::APIBridge::getSchemeSecurityName()

Definition at line 88 of file engine.cpp.

◆ classTag()

std::int64_t hebench::cpp::BaseEngine::classTag ( ) const

inlineoverridevirtual

Retrieves the tag of the class to which this object belongs.

Most significant 8 bits of the 64-bit tag are reserved by C++ wrapper. See ITaggedObject for more details.

Implements hebench::cpp::ITaggedObject.

Definition at line 90 of file engine.hpp.

◆ createBenchmark()

hebench::APIBridge::Handle hebench::cpp::BaseEngine::createBenchmark	(	hebench::APIBridge::Handle	h_bench_desc,
		const hebench::APIBridge::WorkloadParams *	p_params
	)

Creates the benchmark specified by the descriptor.

See also: hebench::APIBridge::initBenchmark()

Definition at line 180 of file engine.cpp.

◆ createEngineObj()

template<class T , typename... Args>

EngineObject * hebench::cpp::BaseEngine::createEngineObj ( Args &&... args ) const

Creates an EngineObject that wraps an object of type T.

Parameters

args	Arguments for constructor of object of type `T`.

Returns: A pointer to an EngineObject instance that wraps the newly constructed object of type T.

Pointers to EngineObject instances make easier to wrap backend internal objects that need to cross the boundary of the API bridge. For easier use, see method createHandle().

See also: createHandle(), retrieveFromHandle()

Definition at line 419 of file engine.hpp.

◆ createHandle()

template<class T , typename... Args>

hebench::APIBridge::Handle hebench::cpp::BaseEngine::createHandle	(	std::uint64_t	size,
		std::int64_t	extra_tags,
		Args &&...	args
	)		const

Encapsulates an object of type T in an opaque HEBench handle.

Parameters

[in]	size	Value to use as the `size` filed for the handle.
[in]	extra_tags	Value to use as the `tag` filed for the handle. This value will be combined with the value for `EngineObject::tag` using binary `OR` operation.
[in]	args	Constructor arguments to construct the object of type T.

Returns: A handle that can cross the boundary of the API bridge.

Exceptions

hebench::cpp::HEBenchError if any of the most significant 8 bits of extra_tags is set, due to these being reserved by ITaggedObject.

This method will construct the object using the arguments specified in args.

See also: retrieveFromHandle(), EngineObject::tag

Definition at line 379 of file engine.hpp.

◆ createObj()

template<class T , typename... Args>

T * hebench::cpp::BaseEngine::createObj ( Args &&... args ) const

Definition at line 437 of file engine.hpp.

◆ createRAII()

template<class T , typename... Args>

std::shared_ptr< T > hebench::cpp::BaseEngine::createRAII ( Args &&... args ) const

Creates a smart pointer of the specified template type.

Parameters

args	Arguments for constructor of object of specified type to be created.

Returns: std::shared_ptr of the specified template type.

The RAII and reference counting properties of smart pointer ensure that the created object is properly destroyed when it goes out of scope and it is the last reference.

The allocation and deallocation mechanisms of the smart pointer use BaseEngine::createObj() and BaseEngine::destroyObj() methods in order to keep the BaseEngine as the allocation manager.

Definition at line 427 of file engine.hpp.

◆ describeBenchmark()

void hebench::cpp::BaseEngine::describeBenchmark	(	hebench::APIBridge::Handle	h_bench_desc,
		hebench::APIBridge::BenchmarkDescriptor *	p_bench_desc,
		hebench::APIBridge::WorkloadParams *	p_default_params,
		std::uint64_t	default_count
	)		const

Definition at line 148 of file engine.cpp.

◆ destroyBenchmark()

void hebench::cpp::BaseEngine::destroyBenchmark ( hebench::APIBridge::Handle h_bench )

Destroys and cleans up a benchmark created by createBenchmark().

Parameters

[in] h_bench Handle to benchmark to destroy.

Exceptions

HEBenchError on invalid handle with error code HEBENCH_ECODE_CRITICAL_ERROR.

Definition at line 199 of file engine.cpp.

◆ destroyObj()

template<class T >

void hebench::cpp::BaseEngine::destroyObj ( T * p ) const

inline

Definition at line 297 of file engine.hpp.

◆ duplicateHandle() [1/2]

hebench::APIBridge::Handle hebench::cpp::BaseEngine::duplicateHandle	(	hebench::APIBridge::Handle	h,
		std::int64_t	check_tags = `0`
	)		const

Duplicates a handle created by createhandle().

Parameters

[in]	h	Handle to duplicate.
[in]	check_tags	Tags to check for. If the input handle does not match this mask in a binary AND test, an exception is thrown.

Returns: A new handle that points to the same internal representation as the input handle. Tags and size are also copied. This duplicate is a shallow copy. See remarks.

Exceptions

hebench::cpp::HEBenchError if tag check fails, or arguments are invalid (invalid check_tags or handle is null).

Handles created by createHandle() point to internal representations that are reference counted. This method, returns a new handle that points to the same internal representation, but increases the reference count. Thus, both handles point to the same internal representation (shallow copy), but destroying each only decrements the reference count. The internal representation is actually destroyed when this reference count reaches 0.

Warning: destroyed handles must not be duplicated. Attempting to duplicate a handle that has been destroyed will cause undefined behavior.

Definition at line 240 of file engine.cpp.

◆ duplicateHandle() [2/2]

hebench::APIBridge::Handle hebench::cpp::BaseEngine::duplicateHandle	(	hebench::APIBridge::Handle	h,
		std::int64_t	new_tag,
		std::int64_t	check_tags
	)		const

Duplicates a handle created by createhandle().

Parameters

[in]	h	Handle to duplicate.
[in]	new_tag	New tag to set in the duplicated handle.
[in]	check_tags	Tags to check for. If the input handle does not match this mask in a binary AND test, an exception is thrown.

Returns: A new handle that points to the same internal representation as the input handle. size is also copied. This duplicate is a shallow copy. See remarks.

Exceptions

hebench::cpp::HEBenchError if tag check fails, or arguments are invalid (invalid check_tags or handle is null).

Handles created by createHandle() point to internal representations that are reference counted. This method, returns a new handle that points to the same internal representation, but increases the reference count. Thus, both handles point to the same internal representation (shallow copy), but destroying each only decrements the reference count. The internal representation is actually destroyed when this reference count reaches 0.

Warning: destroyed handles must not be duplicated. Attempting to duplicate a handle that has been destroyed will cause undefined behavior.

Definition at line 230 of file engine.cpp.

◆ getBenchmarkDescriptionEx()

std::string hebench::cpp::BaseEngine::getBenchmarkDescriptionEx	(	hebench::APIBridge::Handle	h_bench_desc,
		const hebench::APIBridge::WorkloadParams *	p_w_params
	)		const

Retrieves backend specific text description for a benchmark descriptor.

See also: hebench::APIBridge::getBenchmarkDescriptionEx()

Definition at line 56 of file engine.cpp.

◆ getDefaultWorkloadParamsCount()

std::uint64_t hebench::cpp::BaseEngine::getDefaultWorkloadParamsCount ( hebench::APIBridge::Handle h_bench_desc ) const

Retrieves the number of sets of default arguments supported by this benchmark's workload.

Parameters

[in] h_bench_desc Handle to benchmark description to query for information.

Definition at line 139 of file engine.cpp.

◆ getErrorDesc()

const std::string & hebench::cpp::BaseEngine::getErrorDesc ( hebench::APIBridge::ErrorCode err_code )

static

Retrieves the description of a specific error code.

Returns: A string containing the error description, or a default message if error code is not known.

The error code must a standard error code defined in the API bridge or a custom code added through a call to addErrorCode() during this object's initialization.

See also

Definition at line 35 of file engine.cpp.

◆ getLastError()

static hebench::APIBridge::ErrorCode hebench::cpp::BaseEngine::getLastError ( )

inlinestatic

Retrieves the last error that occurred as set by setLastError().

Definition at line 105 of file engine.hpp.

◆ getLastErrorDesc()

static const std::string& hebench::cpp::BaseEngine::getLastErrorDesc ( )

inlinestatic

Retrieves the description of the last error that occurred as set by setLastError().

Definition at line 110 of file engine.hpp.

◆ getWorkloadParamsCount()

std::uint64_t hebench::cpp::BaseEngine::getWorkloadParamsCount ( hebench::APIBridge::Handle h_bench_desc ) const

Retrieves the number of workload parameters for the decribed benchmark.

Parameters

[in] h_bench_desc Handle to benchmark description to query for information.

Definition at line 130 of file engine.cpp.

◆ init()

virtual void hebench::cpp::BaseEngine::init ( )

protectedpure virtual

Initializes the backend engine and populates the backend description.

This method is called automatically during engine initialization.

Derived classes should use this method to initialize this class and populate the descriptions for the benchmarks that this backend will perform; and add error descriptions, scheme and security names for this backend.

See also: addBenchmarkDescription(), addErrorCode(), addSchemeName(), addSecurityName()

◆ matchBenchmark()

std::shared_ptr< BenchmarkDescription > hebench::cpp::BaseEngine::matchBenchmark ( hebench::APIBridge::Handle h_desc ) const

protected

Retrieves the BenchmarkDescription object pointed by the specified handle.

Parameters

[in] h_desc Handle to descriptor as returned by subscribeBenchmarks().

Returns: A smart pointer to the BenchmarkDescription object that is pointed by the specified handle or a null pointer if no match was found.

See also: subscribeBenchmarks()

Definition at line 96 of file engine.cpp.

◆ operator=() [1/2]

BaseEngine& hebench::cpp::BaseEngine::operator= ( BaseEngine && )

delete

◆ operator=() [2/2]

BaseEngine& hebench::cpp::BaseEngine::operator= ( const BaseEngine & )

delete

◆ retrieveFromHandle()

template<class T , typename... Args>

T & hebench::cpp::BaseEngine::retrieveFromHandle	(	hebench::APIBridge::Handle	h,
		std::int64_t	extra_tags = `0`
	)		const

Retrieves the object of type T encapsulated in an opaque HEBench handle by method createHandle().

Parameters

[in]	h	Handle containing the object.
[in]	extra_tags	Value to check against the `tag` for the handle.

Returns: A reference to the object of type T encapsulated in the handle.

Exceptions

hebench::cpp::HEBenchError

if any of the most significant 8 bits of extra_tags is set, or

handle.tag & EngineObject::tag != EngineObject::tag

|| handle.tag & extra_tags != extra_tags

hebench::cpp::EngineObject::tag

static constexpr std::int64_t tag

Used to identify this class when returned as a handle to Test Harness.

Definition: engine_object.hpp:112

Note that once extracted, the object will be statically casted to type T. Due to the nature of the opaque handles, this cast is unsafe, and thus, it is user's responsibility to make sure that the encapsulated object is of the right type (such as using the tag field in the handle for extra information).

See also: createHandle(), EngineObject::tag

Definition at line 397 of file engine.hpp.

◆ schemeName()

const std::unordered_map<hebench::APIBridge::Scheme, std::string>& hebench::cpp::BaseEngine::schemeName ( ) const

inline

Retrieves a dictionary that maps schemes known to this benchmark to their human readable names.

See also: hebench::APIBridge::getSchemeName()

Definition at line 141 of file engine.hpp.

◆ securityName()

const std::unordered_map<hebench::APIBridge::Security, std::string>& hebench::cpp::BaseEngine::securityName ( ) const

inline

Retrieves a dictionary that maps security types known to this benchmark to their human readable names.

See also: hebench::APIBridge::getSchemeSecurityName()

Definition at line 148 of file engine.hpp.

◆ setLastError() [1/2]

void hebench::cpp::BaseEngine::setLastError ( hebench::APIBridge::ErrorCode value )

static

Sets the last error code that occurred.

Parameters

[in] value Error code.

This method is automatically called by C++ wrapper when an exception of type HEBenchError is caught.

Definition at line 44 of file engine.cpp.

◆ setLastError() [2/2]

void hebench::cpp::BaseEngine::setLastError	(	hebench::APIBridge::ErrorCode	value,
		const std::string &	err_desc
	)

static

Sets the last error code that occurred.

Parameters

[in]	value	Error code.
[in]	err_desc	Description of the error.

This method is automatically called by C++ wrapper when an exception of type HEBenchError is caught.

Definition at line 49 of file engine.cpp.

◆ subscribeBenchmarkCount()

std::uint64_t hebench::cpp::BaseEngine::subscribeBenchmarkCount ( ) const

inline

Retrieves the number of benchmarks for which the backend is registering to perform.

See also: hebench::APIBridge::subscribeBenchmarksCount()

Definition at line 155 of file engine.hpp.

◆ subscribeBenchmarks()

void hebench::cpp::BaseEngine::subscribeBenchmarks	(	hebench::APIBridge::Handle *	p_h_bench_descs,
		std::uint64_t	count
	)		const

Retrieves the benchmarks for which the backend is registering to perform.

See also: hebench::APIBridge::subscribeBenchmarks()

Definition at line 106 of file engine.cpp.

Member Data Documentation

◆ tag

constexpr std::int64_t hebench::cpp::BaseEngine::tag = 0x8000000000000000

staticconstexpr

Used to identify this class when returned as a handle to Test Harness.

See also: ITaggedObject

Definition at line 86 of file engine.hpp.

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BaseEngine() [1/3]

◆ BaseEngine() [2/3]

◆ ~BaseEngine()

◆ BaseEngine() [3/3]

Member Function Documentation

◆ addBenchmarkDescription()

◆ addErrorCode()

◆ addSchemeName()

◆ addSecurityName()

◆ classTag()

◆ createBenchmark()

◆ createEngineObj()

◆ createHandle()

◆ createObj()

◆ createRAII()

◆ describeBenchmark()

◆ destroyBenchmark()

◆ destroyObj()

◆ duplicateHandle() [1/2]

◆ duplicateHandle() [2/2]

◆ getBenchmarkDescriptionEx()

◆ getDefaultWorkloadParamsCount()

◆ getErrorDesc()

◆ getLastError()

◆ getLastErrorDesc()

◆ getWorkloadParamsCount()

◆ init()

◆ matchBenchmark()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ retrieveFromHandle()

◆ schemeName()

◆ securityName()

◆ setLastError() [1/2]

◆ setLastError() [2/2]

◆ subscribeBenchmarkCount()

◆ subscribeBenchmarks()

Member Data Documentation

◆ tag