profiling Namespace Reference

Definition of utility struct and function used by the profiling targets. More...

Namespaces
namespace	detail

Classes
class	Exception
	profiling exception class More...
struct	VersionInfo
	structure defining the values used for semantic versioning of the profiling system More...
struct	ProfilingHooks
	Set of all function pointers used for profiling. More...
class	ProfilingRegion
	Scope guard that marks a region of code for profiling. More...
struct	ProfilingSystemArguments
	Command-line arguments for profiling, as they may be parsed by code that uses profiling. More...
class	ProfilingSystem
	Scope guard, whose constructor starts the profiling system, and whose destructor stops the profiling system. More...
class	TimedRegion
	Scope guard that records wall clock time elapsed and marks region beginning and end by writing to a given output stream. More...

Typedefs
using	ProfilingInterfaceVersionFunc = uint64_t (*)()
	Type of a callback for getting the version number of the profiling interface that the library provides.
using	ProfilingInitializeFunc = int32_t (*)(const char*)
	Type of a callback for initializing the profiling library.
using	BeginProfilingRegionFunc = void (*)(const char*)
	Type of a callback for beginning a profiling region.
using	EndProfilingRegionFunc = void (*)()
	Type of a callback for ending a profiling region that was previously begun.
using	CreateProfilingSectionFunc = uint32_t (*)(const char*)
	Type of a callback for creating a profiling section.
using	DestroyProfilingSectionFunc = void (*)(uint32_t)
	Type of a callback for destroying a profiling section.
using	BeginProfilingSectionFunc = void (*)(uint32_t)
	Type of a callback for beginning a profiling section.
using	EndProfilingSectionFunc = void (*)(uint32_t)
	Type of a callback for ending a profiling section that was previously begun.
using	ProfilingFinalizeFunc = void (*)()
	Type of a callback for finalizing the profiling library.

Functions
uint64_t	PackVersionInfo (uint16_t aEpoch, uint16_t aMajor, uint16_t aMinor, uint16_t aPatch)
	Combines four uint16_t versioning values into one uint64_t.
VersionInfo	UnpackVersionInfo (const uint64_t packedVersionInfo)
	Unpacks the profiling library's version information.
uint32_t	CreateProfilingSection (const char label[])
	Create a profiling section.
void	DestroyProfilingSection (uint32_t sectionId)
	Destroy a profiling section that was created by CreateProfilingSection.
void	BeginProfilingSection (uint32_t sectionId)
	Begin a previously created profiling section.
void	EndProfilingSection (uint32_t sectionId)
	End a previously created and begun profiling section.
ProfilingSystemArguments &	GlobalProfilingSystemArguments ()
	Reference to the command-line arguments for profiling.

Variables
constexpr const char	cPROFILING_INTERFACE_VERSION_SYMBOL [] = "AfsimProfilingInterfaceVersion"
	Name of symbol (to load from shared library) for the callback that gets the version number of the profiling interface.
constexpr const char	cPROFILING_INITIALIZE_SYMBOL [] = "AfsimProfilingInitialize"
	Name of symbol (to load from shared library) for the callback that initializes the profiling library.
constexpr const char	cPROFILING_BEGIN_REGION_SYMBOL [] = "AfsimProfilingBeginRegion"
	Name of symbol (to load from shared library) for the callback that begins a profiling region.
constexpr const char	cPROFILING_END_REGION_SYMBOL [] = "AfsimProfilingEndRegion"
	Name of symbol (to load from shared library) for the callback that ends a profiling region that was previously begun.
constexpr const char	cPROFILING_CREATE_SECTION_SYMBOL [] = "AfsimProfilingCreateSection"
	Name of symbol (to load from shared library) for the callback that creates a profiling section.
constexpr const char	cPROFILING_DESTROY_SECTION_SYMBOL [] = "AfsimProfilingDestroySection"
	Name of symbol (to load from shared library) for the callback that destroys a profiling section.
constexpr const char	cPROFILING_BEGIN_SECTION_SYMBOL [] = "AfsimProfilingBeginSection"
	Name of symbol (to load from shared library) for the callback that begins a profiling section.
constexpr const char	cPROFILING_END_SECTION_SYMBOL [] = "AfsimProfilingEndSection"
	Name of symbol (to load from shared library) for the callback that ends a profiling section that was previously begun.
constexpr const char	cPROFILING_FINALIZE_SYMBOL [] = "AfsimProfilingFinalize"
	Name of symbol (to load from shared library) for the callback that finalizes the profiling library.

Detailed Description

Definition of utility struct and function used by the profiling targets.

Declaration of scope guard for enabling profiling.

Declaration of a "scope guard" to mark regions of code for profiling.

Interface required by a shared library that implements profiling "hooks" for the profiling system.

For the interface that starts and stops the entire profiling system, please see ProfilingSystem.hpp. For the interface that identifies a region to profile, please see ProfilingRegion.hpp.

The profiling system loads a shared library at run time. That may be the AFPerf library that AFSIM builds and installs, or it may be an alternate library. The shared library must contain the five symbols which are the string constants defined in this header file. Loading a symbol must result in a function pointer that is compatible with the corresponding function pointer alias in this header file.

Using profiling hooks with C89-style parameters (e.g., no std::string or other C++ types) avoids potential issues with ABI incompatibility, due to different compiler versions or C++ language versions. The hope is that an alternate profiling library need not be built with the same compiler version as AFSIM. The profiling library should still be built with the same compiler brand (e.g., GCC or MSVC) as AFSIM.

The profiling system loads a shared library at run time. For the interface that the shared library must implement, please see ProfilingHooks.hpp. For the interface for profiling a region of C++ code, please see ProfilingRegion.hpp.

Typedef Documentation

BeginProfilingRegionFunc

using profiling::BeginProfilingRegionFunc = void (*)(const char*)

Type of a callback for beginning a profiling region.

Loading the cPROFILING_BEGIN_REGION_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

BeginProfilingSectionFunc

using profiling::BeginProfilingSectionFunc = void (*)(uint32_t)

Type of a callback for beginning a profiling section.

Loading the cPROFILING_BEGIN_SECTION_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

CreateProfilingSectionFunc

using profiling::CreateProfilingSectionFunc = uint32_t (*)(const char*)

Type of a callback for creating a profiling section.

Loading the cPROFILING_CREATE_SECTION_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

DestroyProfilingSectionFunc

using profiling::DestroyProfilingSectionFunc = void (*)(uint32_t)

Type of a callback for destroying a profiling section.

Loading the cPROFILING_DESTROY_SECTION_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

EndProfilingRegionFunc

using profiling::EndProfilingRegionFunc = void (*)()

Type of a callback for ending a profiling region that was previously begun.

Loading the cPROFILING_END_REGION_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

EndProfilingSectionFunc

using profiling::EndProfilingSectionFunc = void (*)(uint32_t)

Type of a callback for ending a profiling section that was previously begun.

Loading the cPROFILING_END_SECTION_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

ProfilingFinalizeFunc

using profiling::ProfilingFinalizeFunc = void (*)()

Type of a callback for finalizing the profiling library.

Loading the cPROFILING_FINALIZE_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

ProfilingInitializeFunc

using profiling::ProfilingInitializeFunc = int32_t (*)(const char*)

Type of a callback for initializing the profiling library.

Loading the cPROFILING_INITIALIZE_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

ProfilingInterfaceVersionFunc

using profiling::ProfilingInterfaceVersionFunc = uint64_t (*)()

Type of a callback for getting the version number of the profiling interface that the library provides.

Loading the cPROFILING_INTERFACE_VERSION_SYMBOL symbol must produce a function pointer that is compatible with this function pointer alias.

Please see ProfilingHooks for details.

Function Documentation

BeginProfilingSection()

PROFILING_EXPORT void profiling::BeginProfilingSection

(

uint32_t

sectionId

)

Begin a previously created profiling section.

Parameters

sectionId

A section key returned by CreateProfilingSection. The key must not refer to a section that has been destroyed.

Every section that has been begun must be ended. After being ended, a section may be begun again.

Different threads may not begin or end the same section concurrently. However, different threads are permitted to begin or end different sections concurrently.

References profiling::detail::GetGlobalProfilingHooks(), and profiling::ProfilingHooks::mBeginSection.

CreateProfilingSection()

PROFILING_EXPORT uint32_t profiling::CreateProfilingSection

(

const char

label[]

)

Create a profiling section.

Parameters

label

The section's label.

Returns

The section's key.

Section labels need not be unique. Calling this function twice with the same label will result in two distinct sections, with different keys. This is useful for timing things that happen inside thread-parallel code.

Sections differ from regions (as created by ProfilingRegion) in the following ways.

1. Sections are allowed to overlap partially. (This is not true for regions. Given any two regions, they are either disjoint, or one contains the other entirely. This means that one can always map regions onto a single timeline.)
2. Section creation happens separately from beginning a section.
3. Section destruction happens separately from ending a section.

All profiling libraries shall let separate threads begin or end (but not necessarily create or destroy) separate sections concurrently. Profiling libraries shall make this thread safe at least. As a minimum quality-of-implementation requirement, they should not synchronize (e.g., via mutexes or atomic operations) when beginning or ending a section. This, plus (1) above, make sections the right idiom for timing events happening concurrently on separate threads. (We do not permit multiple threads to begin or end the same section concurrently.)

References profiling::detail::GetGlobalProfilingHooks(), and profiling::ProfilingHooks::mCreateSection.

DestroyProfilingSection()

PROFILING_EXPORT void profiling::DestroyProfilingSection

(

uint32_t

sectionId

)

Destroy a profiling section that was created by CreateProfilingSection.

Destroy a profiling section.

Parameters

sectionId

A section key returned by CreateProfilingSection.

You must call DestroyProfilingSection exactly once for every unique section key returned by CreateProfilingSection.

References profiling::detail::GetGlobalProfilingHooks(), and profiling::ProfilingHooks::mDestroySection.

EndProfilingSection()

PROFILING_EXPORT void profiling::EndProfilingSection

(

uint32_t

sectionId

)

End a previously created and begun profiling section.

Parameters

sectionId

A section key returned by CreateProfilingSection. The key must not refer to a section that has been destroyed. The section must have been begun (via BeginProfilingSection).

The key must refer to a section that has been begun. Every section that has been begun must be ended. After being ended, a section may be begun again.

References profiling::detail::GetGlobalProfilingHooks(), and profiling::ProfilingHooks::mEndSection.

GlobalProfilingSystemArguments()

PROFILING_EXPORT ProfilingSystemArguments & profiling::GlobalProfilingSystemArguments

(

)

Reference to the command-line arguments for profiling.

Referenced by main(), and WsfProfilingApplicationExtension::ProcessCommandLine().

PackVersionInfo()

uint64_t profiling::PackVersionInfo ( uint16_t aEpoch, uint16_t aMajor, uint16_t aMinor, uint16_t aPatch )

inline

Combines four uint16_t versioning values into one uint64_t.

Each value takes up 16 bits (disjointed) in the following order [Epoch][Major][Minor][Patch].

Parameters

aEpoch	- version value which when changed indicates a reset of the versioning system.
aMajor	- version value which when changed indicates incompatible API changes.
aMinor	- version value which when changed indicates a change in the implementation that maintains compatibility. When a library indicates a non-zero minor value, that represents a minimum version of the profiling system with which the library is compatible.
aPatch	- version value which when changed indicates bug fixes that maintain compatibility.

Returns

packed uint64_t value encoding versioning values

UnpackVersionInfo()

VersionInfo profiling::UnpackVersionInfo ( const uint64_t packedVersionInfo )

inline

Unpacks the profiling library's version information.

Parameters

packedVersionInfo

Return value of the profiling library's AfsimProfilingInterfaceVersion function.

References profiling::VersionInfo::mEpoch, profiling::VersionInfo::mMajor, profiling::VersionInfo::mMinor, and profiling::VersionInfo::mPatch.

Variable Documentation

cPROFILING_BEGIN_REGION_SYMBOL

const char profiling::cPROFILING_BEGIN_REGION_SYMBOL[] = "AfsimProfilingBeginRegion"

constexpr

Name of symbol (to load from shared library) for the callback that begins a profiling region.

cPROFILING_BEGIN_SECTION_SYMBOL

const char profiling::cPROFILING_BEGIN_SECTION_SYMBOL[] = "AfsimProfilingBeginSection"

constexpr

Name of symbol (to load from shared library) for the callback that begins a profiling section.

cPROFILING_CREATE_SECTION_SYMBOL

const char profiling::cPROFILING_CREATE_SECTION_SYMBOL[] = "AfsimProfilingCreateSection"

constexpr

Name of symbol (to load from shared library) for the callback that creates a profiling section.

cPROFILING_DESTROY_SECTION_SYMBOL

const char profiling::cPROFILING_DESTROY_SECTION_SYMBOL[] = "AfsimProfilingDestroySection"

constexpr

Name of symbol (to load from shared library) for the callback that destroys a profiling section.

cPROFILING_END_REGION_SYMBOL

const char profiling::cPROFILING_END_REGION_SYMBOL[] = "AfsimProfilingEndRegion"

constexpr

Name of symbol (to load from shared library) for the callback that ends a profiling region that was previously begun.

cPROFILING_END_SECTION_SYMBOL

const char profiling::cPROFILING_END_SECTION_SYMBOL[] = "AfsimProfilingEndSection"

constexpr

Name of symbol (to load from shared library) for the callback that ends a profiling section that was previously begun.

cPROFILING_FINALIZE_SYMBOL

const char profiling::cPROFILING_FINALIZE_SYMBOL[] = "AfsimProfilingFinalize"

constexpr

Name of symbol (to load from shared library) for the callback that finalizes the profiling library.

cPROFILING_INITIALIZE_SYMBOL

const char profiling::cPROFILING_INITIALIZE_SYMBOL[] = "AfsimProfilingInitialize"

constexpr

Name of symbol (to load from shared library) for the callback that initializes the profiling library.

cPROFILING_INTERFACE_VERSION_SYMBOL

const char profiling::cPROFILING_INTERFACE_VERSION_SYMBOL[] = "AfsimProfilingInterfaceVersion"

constexpr

Name of symbol (to load from shared library) for the callback that gets the version number of the profiling interface.