Classes
class	Archive

class	Benchmark

class	ExceptionSettings
	A Singleton storing exception settings (currently only one flag) More...

class	Experiment

class	ExperimentResult

class	Factory

struct	FieldReader

class	GenericFactory

class	JUnit

class	Pimpl

class	Printer

struct	RAMReport
	Contans all Memory measurements (in bytes) More...

class	ResultTable

class	Statistics

class	TestFixture

class	TestVector

class	ThreadTestFixture

class	UserDefinedMeasurement
	Base class that the user must derive user-defined measurements from. More...

class	UserDefinedMeasurementCollector

class	UserDefinedMeasurementTemplate
	Base class that the user must derive user-defined measurements from. More...

Typedefs
using	UDMAggregationTable = std::vector< std::pair< std::string, std::function< double(void)> >>
	Describes, which aggregations should be computed on a user-defined measurement. More...

Functions
CELERO_EXPORT void	AddExperimentCompleteFunction (std::function< void(std::shared_ptr< celero::Experiment >)> x)
	Add a function to call when a experiment is completed. More...

CELERO_EXPORT void	AddExperimentResultCompleteFunction (std::function< void(std::shared_ptr< celero::ExperimentResult >)> x)
	Add a function to call when a experiment is completed. More...

CELERO_EXPORT std::shared_ptr< celero::Benchmark >	RegisterTest (const char groupName, const char benchmarkName, const uint64_t samples, const uint64_t iterations, const uint64_t threads, std::shared_ptr< celero::Factory > experimentFactory, const double target=-1)
	Adds a new test to the list of tests to be executed. More...

CELERO_EXPORT std::shared_ptr< Benchmark >	RegisterBaseline (const char groupName, const char benchmarkName, const uint64_t samples, const uint64_t iterations, const uint64_t threads, std::shared_ptr< Factory > experimentFactory)
	Adds a new test baseline to the list of test baseliness to be executed. More...

CELERO_EXPORT std::vector< uint64_t >	BuildDistribution (uint64_t numberOfSamples, uint64_t iterationsPerSample)
	Builds a distribution of total system measurement error. More...

CELERO_EXPORT void	Run (int argc, char **argv)
	The main test executor.

CELERO_EXPORT void	RunDistribution (uint64_t iterationsPerSample)
	Builds a .csv file to help determine Celero's measurement distribution.

std::pair< bool, uint64_t >	RunAndCatchSEHExc (TestFixture &test, uint64_t threads, uint64_t calls, std::shared_ptr< celero::TestFixture::ExperimentValue > experimentValue)
	Run test and catch SEH exceptions if they are supported by compiler.

std::pair< bool, uint64_t >	RunAndCatchExc (TestFixture &test, uint64_t threads, uint64_t calls, std::shared_ptr< celero::TestFixture::ExperimentValue > experimentValue)
	Run test and catch all exceptions we can.

CELERO_EXPORT int64_t	GetRAMSystemTotal ()

CELERO_EXPORT int64_t	GetRAMSystemAvailable ()

CELERO_EXPORT int64_t	GetRAMSystemUsed ()

CELERO_EXPORT int64_t	GetRAMSystemUsedByCurrentProcess ()
	The sum of the physical RAM used by the current process and the virtual RAM used by the current process.

CELERO_EXPORT int64_t	GetRAMPhysicalTotal ()
	The total physical RAM, in bytes. More...

CELERO_EXPORT int64_t	GetRAMPhysicalAvailable ()
	The total physical RAM available to the current process, in bytes. More...

CELERO_EXPORT int64_t	GetRAMPhysicalUsed ()
	The total amount of physical RAM minus the amount of physical RAM which is available.

CELERO_EXPORT int64_t	GetRAMPhysicalUsedByCurrentProcess ()
	On Windows, this is defined by the Working Set Size. More...

CELERO_EXPORT int64_t	GetRAMPhysicalUsedByCurrentProcessPeak ()

CELERO_EXPORT int64_t	GetRAMVirtualTotal ()
	The total amount of Virtual RAM (page file size). More...

CELERO_EXPORT int64_t	GetRAMVirtualAvailable ()
	The amount of non-physical memory (page file) available. More...

CELERO_EXPORT int64_t	GetRAMVirtualUsed ()
	The total virtual RAM minus the available virtual RAM.

CELERO_EXPORT int64_t	GetRAMVirtualUsedByCurrentProcess ()
	On Windows, this is defined as the commit charge. More...

CELERO_EXPORT celero::RAMReport	GetRAMReport ()
	Returns a RAMReport class containing all RAM measurements.

template<class T >
void	DoNotOptimizeAway (T &&x)
	DoNotOptimizeAway More...

template<class T >
void	DoNotOptimizeAway (std::function< T(void)> &&x)
	Specialization for std::function objects which return a value.

template<>
CELERO_EXPORT void	DoNotOptimizeAway (std::function< void(void)> &&x)
	Specialization for std::function objects which return void.

constexpr uint64_t	UsPerSec (1000000)
	Quick definition of the number of microseconds per second.

CELERO_EXPORT int	Random ()
	Drop-in replacement for std::rand();.

Variables
constexpr double	UsToSec {1.0e-6}
	Conversion from Microseconds to Seconds.

constexpr auto	SecondsPerMinute {60}

constexpr auto	SecondsPerHour {SecondsPerMinute * 60}

Detailed Description

Author: John Farrier

Copyright: Copyright 2015-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: John Farrier

Copyright: Copyright 2015-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Ideas from Nick Brunn's Hayai (https://github.com/nickbruun/hayai) were used and I likely owe him a beer.

Special thanks to the band "3" for providing the development soundtrack.

"Iterations" refers to how many loops of the test function are measured as a time. For very fast code, many iterations would help amoratize measurement error.

"Samples" refers to how many sets of "iterations" will be performed. Each "sample" is a single measurement. Set to 0 to have Celero decide how many samples are required for a minimally significant answer.

It is highly encouraged to only run this code compiled in a "Release" mode to use all available optimizations.

Author: John Farrier

Copyright: Copyright 2015-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Special thanks to the bands "3" and "Coheed and Cambria" for providing the development soundtrack.

"Iterations" refers to how many loops of the test function are measured as a time. For very fast code, many iterations would help amoratize measurement error.

"Samples" refers to how many sets of "Iterations" will be performed. Each "sample" is a single measurement.

It is highly encouraged to only run this code compiled in a "Release" mode to use all available optimizations.

Author: Peter Azmanov

Copyright: Copyright 2015-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: John Farrier

Copyright: Copyright 2018-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: John Farrier

Copyright: Copyright 2015-2025 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: Ivan Shynkarenka

Copyright: Copyright 2015-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: Lukas Barth

Copyright: Copyright 2015-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Author: Lukas Barth, John Farrier

Copyright: Copyright 2015-2023 John Farrier

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Typedef Documentation

◆ UDMAggregationTable

using celero::UDMAggregationTable = typedef std::vector<std::pair<std::string, std::function<double(void)> >>

Describes, which aggregations should be computed on a user-defined measurement.

The string names the aggregation, the UDMAggregateFunction is the function that will be called on the collected vector of user-defined measurements.

Function Documentation

◆ AddExperimentCompleteFunction()

CELERO_EXPORT void celero::AddExperimentCompleteFunction ( std::function< void(std::shared_ptr< celero::Experiment >)> x )

Add a function to call when a experiment is completed.

This will be called at the end of a complete experiment (benchmark + experiment results.)

◆ AddExperimentResultCompleteFunction()

void celero::AddExperimentResultCompleteFunction ( std::function< void(std::shared_ptr< celero::ExperimentResult >)> x )

Add a function to call when a experiment is completed.

This will be called at the end of every benchmark or user experiment upon completion.

◆ BuildDistribution()

std::vector< uint64_t > celero::BuildDistribution	(	uint64_t	numberOfSamples,
		uint64_t	iterationsPerSample
	)

Builds a distribution of total system measurement error.

Collects results from Celero for analysis of a hard-coded internal trivial measurement case.

The result vector contains microseconds for each trivial timer sample. The purpose is to be able to characterize the generic distribution of results on a given system.

This is just an attempt to characterize the distribution, not quantify it.

◆ DoNotOptimizeAway()

template<class T >

void celero::DoNotOptimizeAway ( T && x )

DoNotOptimizeAway

Used to prevent compiler optimization of a variable that performs no real purpose other than to participate in a benchmark

Consider the following trivial benchmark:

BASELINE(...)
{
    int x = 0;
    for(int i = 0; i < 64; i++)
    {
        x += i;
    }
}

Using Ubuntu clang v3.0, the resultant assembly is highly optimized as one might expect, but not terribly useful for baselining:

/// movl    $2016, %eax             # imm = 0x7E0
/// ret
///

Now, replace the inner loop with a call to DoNotOptimizeAway:

DoNotOptimizeAway(x += i);

The result is now a loop which is meaningful for establishing a baseline.

/// xorl    %ecx, %ecx
/// xorl    %eax, %eax
/// .LBB0_1:                                # =>This Inner Loop Header: Depth=1
/// addl    %ecx, %eax
/// incl    %ecx
/// cmpl    $64, %ecx
/// jne .LBB0_1
/// ret
///

GCC 4.8 gives similar results.

gcc.godbolt.org permalink: http://goo.gl/lsngwX

Folly uses a simple bit of inline assembly:
> template <class T>
> void doNotOptimizeAway(T&& datum) {
> asm volatile("" : "+r" (datum));
>}

It would be great if that were portable with respect to both compilers and 32/64-bit targets.

◆ GetRAMPhysicalAvailable()

int64_t celero::GetRAMPhysicalAvailable ( )

The total physical RAM available to the current process, in bytes.

On Windows, this is defined as "This is the amount of physical memory that can be immediately reused without having to write its contents to disk first. It is the sum of the size of the standby, free, and zero lists." https://msdn.microsoft.com/en-us/library/windows/desktop/aa366770(v=vs.85).aspx

◆ GetRAMPhysicalTotal()

int64_t celero::GetRAMPhysicalTotal ( )

The total physical RAM, in bytes.

https://msdn.microsoft.com/en-us/library/windows/desktop/aa366770(v=vs.85).aspx

◆ GetRAMPhysicalUsedByCurrentProcess()

int64_t celero::GetRAMPhysicalUsedByCurrentProcess ( )

On Windows, this is defined by the Working Set Size.

The working set size is defined as "The working set of a process is the set of pages in the virtual address space of the process that are currently resident in physical memory. The working set contains only pageable memory allocations; nonpageable memory allocations such as Address Windowing Extensions (AWE) or large page allocations are not included in the working set." https://msdn.microsoft.com/en-us/library/windows/desktop/ms684877(v=vs.85).aspx https://msdn.microsoft.com/en-us/library/windows/desktop/cc441804(v=vs.85).aspx

◆ GetRAMVirtualAvailable()

int64_t celero::GetRAMVirtualAvailable ( )

The amount of non-physical memory (page file) available.

On Windows, this is defined by the amount of page file that the current process has access to. It is not the total available on the system. From the Windows documentation: "The maximum amount of memory the current process can commit, in bytes. This value is equal to or smaller than the system-wide available commit value."

◆ GetRAMVirtualTotal()

int64_t celero::GetRAMVirtualTotal ( )

The total amount of Virtual RAM (page file size).

On Windows, this is defined by the amount of page file that the current process has access to. It is not the total available on the system. From the Windows documentation: "The current committed memory limit for the system or the current process, whichever is smaller, in bytes. To get the system-wide committed memory limit, call GetPerformanceInfo."

◆ GetRAMVirtualUsedByCurrentProcess()

int64_t celero::GetRAMVirtualUsedByCurrentProcess ( )

On Windows, this is defined as the commit charge.

"The Commit Charge value in bytes for this process. Commit Charge is the total amount of memory that the memory manager has committed for a running process." https://msdn.microsoft.com/en-us/library/windows/desktop/ms684877(v=vs.85).aspx

◆ RegisterBaseline()

CELERO_EXPORT std::shared_ptr<Benchmark> celero::RegisterBaseline	(	const char *	groupName,
		const char *	benchmarkName,
		const uint64_t	samples,
		const uint64_t	iterations,
		const uint64_t	threads,
		std::shared_ptr< Factory >	experimentFactory
	)

Adds a new test baseline to the list of test baseliness to be executed.

All test baselines must be registered prior to calling celer::Run().

Parameters

groupName	The name of the Test Group that the baseline is associated with.
benchmarkName	A unique name for a specific test baseline within a Test Group.
samples	The total number of times to execute the Test baseline. (Each sample contains one or more iterations.)
iterations	The total number of iterations per Test baseline sample.
threads	The total number of threads per Test baseline.
experimentFactory	The factory implementation for the test baseline.

Returns: a pointer to a Benchmark instance representing the given test.

◆ RegisterTest()

std::shared_ptr< celero::Benchmark > celero::RegisterTest	(	const char *	groupName,
		const char *	benchmarkName,
		const uint64_t	samples,
		const uint64_t	iterations,
		const uint64_t	threads,
		std::shared_ptr< celero::Factory >	experimentFactory,
		const double	target = `-1`
	)

Adds a new test to the list of tests to be executed.

All tests must be registered prior to calling celer::Run().

Parameters

groupName	The name of the Test Group. Used for retrieving the associated baseline.
benchmarkName	A unique name for a specific test within a Test Group.
samples	The total number of times to execute the Test. (Each test contains iterations.)
iterations	The total number of iterations per Test.
threads	The total number of threads per Test sample.
experimentFactory	The factory implementation for the test.

Returns: a pointer to a Benchmark instance representing the given test.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ UDMAggregationTable

Function Documentation

◆ AddExperimentCompleteFunction()

◆ AddExperimentResultCompleteFunction()

◆ BuildDistribution()

◆ DoNotOptimizeAway()

◆ GetRAMPhysicalAvailable()

◆ GetRAMPhysicalTotal()

◆ GetRAMPhysicalUsedByCurrentProcess()

◆ GetRAMVirtualAvailable()

◆ GetRAMVirtualTotal()

◆ GetRAMVirtualUsedByCurrentProcess()

◆ RegisterBaseline()

◆ RegisterTest()