PEARL
Parallel Event Access and Replay Library
List of all members
pearl::TraceArchive Class Referenceabstract

Abstract representation of a trace experiment archive. More...

#include <pearl/TraceArchive.h>

Inheritance diagram for pearl::TraceArchive:
pearl::uncopyable::Uncopyable

Public Member Functions

Access archive properties
std::string getAnchorName () const
 Get archive anchor name. More...
 
std::string getArchiveDirectory () const
 Get archive directory name. More...
 
Access global definition data
GlobalDefsgetDefinitions ()
 Get global definitions. More...
 
Access local mapping & event trace data
void openTraceContainer (const LocationGroup &locGroup)
 Open trace data container. More...
 
void closeTraceContainer ()
 Close trace data container. More...
 
LocalIdMaps * getIdMaps (const Location &location)
 Get definition identifier mappings. More...
 
LocalTracegetTrace (const GlobalDefs &defs, const Location &location, LocalIdMaps *idMaps=0)
 Get trace data. More...
 

Static Public Member Functions

Archive management
static TraceArchiveopen (const std::string &anchorName)
 Open an experiment archive. More...
 

Constructors & destructor

virtual ~TraceArchive ()
 Destructor. More...
 
 TraceArchive (const std::string &anchorName, const std::string &archiveDir)
 Constructor. More...
 

Detailed Description

The TraceArchive class provides an abstract representation for trace experiment archives. It defines a common interface to open archives and to read their global definitions data as well as per-location event trace data, while hiding the details specific to different types of archives. Currently, the following types of experiment archives are supported:

To work with trace experiment archives, first an archive handle has to be created using the TraceArchive::open() factory method:

pearl::TraceArchive* archive = pearl::TraceArchive::open("experiment/traces.otf2");

In this example, the OTF2 experiment archive defined by the anchor file "traces.otf2" inside the "experiment" directory is opened, and a corresponding archive handle assigned to the archive variable which can then be used to access the archive data.

Now, the global definition data of the experiment can be read:

pearl::GlobalDefs* defs = archive->getDefinitions();

Before any event trace data can be read from the experiment archive, the corresponding trace data container needs to be opened. Following the general PEARL usage model that each PEARL process only handles the event trace data of one target application process, the corresponding location group retrieved from the global definitions (here stored in the variable locGroup) is used to open the associated trace data container:

archive->openTraceContainer(locGroup);
Warning
In a multi-process context (e.g., when using MPI), the call to openTraceContainer(), as well as the closeTraceContainer() call introduced below, are collective operations accross all processes!

Next, the event trace data of a particular location within the perviously specified location group can be read:

pearl::LocalTrace* trace = archive->getTrace(defs, location);
Attention
Reading event trace data is the only archive operation that can be safely used in a multi-threaded context! All other operations on an experiment archive should only be executed by a single thread.
Remarks
In most cases, reading the event trace data also requires loading identifier mapping tables used to convert process-local definition IDs to global definition identifiers. The two-parameter call to getTrace() as shown in the example above implicitly takes care of loading these identifier mappings. However, for debugging purposes it may be desired to separately load the identifier mapping information and the trace data. Please see the description of the getIdMaps() member function for more details.

Finally, the event trace container can be closed and the archive handle destroyed, which implicitly also closes the archive:

delete archive;

Note that this does neither delete the global definitions object nor any trace data objects retrieved from the archive, as both the getDefinitions() and getTrace() member functions transfer ownership of the created object to the caller.

Constructor & Destructor Documentation

◆ ~TraceArchive()

virtual pearl::TraceArchive::~TraceArchive ( )
virtual

Implicitly closes the trace experiment archive, releases all allocated resources, and destroys the handle object.

◆ TraceArchive()

pearl::TraceArchive::TraceArchive ( const std::string &  anchorName,
const std::string &  archiveDir 
)
protected

Creates a new trace experiment archive handle and initializes its data members with the anchor file/directory name anchorName and the experiment archive directory name archiveDirectory.

Parameters
anchorNameName of the trace experiment archive anchor file/directory
archiveDirName of the trace experiment archive directory

Member Function Documentation

◆ closeTraceContainer()

void pearl::TraceArchive::closeTraceContainer ( )

Closes the trace data container previously opened by a call to openTraceContainer().

Warning
In a multi-process context (e.g., when using MPI), this member function is a collective operation across all processes! As it involves communication, there may be additional restrictions on which thread is allowed to call it in a multi-threaded setup.

◆ getAnchorName()

std::string pearl::TraceArchive::getAnchorName ( ) const

Returns the name of the trace experiment archive anchor. Depending on the archive type, this can be the name of a file (e.g., for OTF2 trace archives) or the archive directory (e.g., for EPIK trace archives).

Returns
Archive anchor name

◆ getArchiveDirectory()

std::string pearl::TraceArchive::getArchiveDirectory ( ) const

Returns the name of the trace experiment archive directory. If the archive anchor is a directory (e.g., for EPIK trace archives), the return value is identical to the anchor name. Otherwise (e.g., for OTF2 trace archives), it refers to the directory where the anchor file is located.

Returns
Archive directory name

◆ getDefinitions()

GlobalDefs* pearl::TraceArchive::getDefinitions ( )

Reads the global definition data from the trace experiment archive and creates a new global definitions object providing access to it. The definitions object's ownership is transferred to the caller.

Returns
Pointer to global definitions object

◆ getIdMaps()

LocalIdMaps* pearl::TraceArchive::getIdMaps ( const Location location)
Note
This method is intended for debugging purposes. It should only be used if it is desired to load the local-to-global definition identifier mapping data separately from the trace data. Usually, it is sufficient to call getTrace() with the default idMaps=0 argument, which will implicitly load the mapping information.

Reads the local-to-global definition identifier mapping information for the given location from the trace experiment archive (if available) and creates a new mapping data object. The mapping information can not be accessed directly; it is only intended to be passed as the idMaps argument to a call to getTrace(). The mapping data object's ownership is transferred to the caller.

Note
The given location has to be attached to the location group provided to the openTraceContainer() call.
Parameters
locationLocation whose mapping data should be read
Returns
Pointer to mapping data object

◆ getTrace()

LocalTrace* pearl::TraceArchive::getTrace ( const GlobalDefs defs,
const Location location,
LocalIdMaps *  idMaps = 0 
)

Reads the event trace data for the given location from the trace experiment archive and creates a new trace data object providing access to it. References to definitions will be resolved using the local-to-global definition identifier mapping data provided in idMaps and the global definitions object defs, retrieved by a previous call to getDefinitions(). If idMaps is 0, the mapping data will be automatically read from the experiment archive. The trace data object's ownership is transferred to the caller.

Note
The given location has to be attached to the location group provided to the openTraceContainer() call.
This member function takes ownership of the mapping data object idMaps and deletes it once the trace data has been read.
Parameters
defsGlobal definitions object
locationLocation whose trace data should be read
idMapsPointer to identifier mapping data object. If 0, mappings will be read from the experiment archive.
Returns
Pointer to trace data object

◆ open()

static TraceArchive* pearl::TraceArchive::open ( const std::string &  anchorName)
static

This factory method opens the trace experiment archive specified by the given anchor file/directory anchorName and returns a new archive handle if successful.

Parameters
anchorNameName of the trace experiment archive anchor file/directory
Returns
Pointer to archive handle object

◆ openTraceContainer()

void pearl::TraceArchive::openTraceContainer ( const LocationGroup locGroup)

Opens the trace data container storing the event data of the given group of locations locGroup. This member function has to be called before trace data objects can be retrieved via getTrace().

Warning
In a multi-process context (e.g., when using MPI), this member function is a collective operation across all processes! As it involves communication, there may be additional restrictions on which thread is allowed to call it in a multi-threaded setup.
Parameters
locGroupLocationGroup whose trace container should be opened

The documentation for this class was generated from the following file:
pearl::TraceArchive::openTraceContainer
void openTraceContainer(const LocationGroup &locGroup)
Open trace data container.
pearl::LocalTrace
Container class for local event traces.
Definition: LocalTrace.h:58
pearl::TraceArchive::open
static TraceArchive * open(const std::string &anchorName)
Open an experiment archive.
pearl::GlobalDefs
Stores the global definitions of a tracing experiment.
Definition: GlobalDefs.h:63
pearl::TraceArchive
Abstract representation of a trace experiment archive.
Definition: TraceArchive.h:132
pearl::TraceArchive::closeTraceContainer
void closeTraceContainer()
Close trace data container.
pearl::TraceArchive::getDefinitions
GlobalDefs * getDefinitions()
Get global definitions.
pearl::TraceArchive::getTrace
LocalTrace * getTrace(const GlobalDefs &defs, const Location &location, LocalIdMaps *idMaps=0)
Get trace data.

Scalasca    Copyright © 1998–2019 Forschungszentrum Jülich GmbH, Jülich Supercomputing Centre
Copyright © 2009–2015 German Research School for Simulation Sciences GmbH, Laboratory for Parallel Programming