PEARL
Parallel Event Access and Replay Library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Member Functions | Static Public Member Functions
pearl::TraceArchive Class Reference

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

#include <pearl/TraceArchive.h>

List of all members.

Public Member Functions

std::string getAnchorName () const
 Get archive anchor name.
std::string getArchiveDirectory () const
 Get archive directory name.
GlobalDefsgetDefinitions ()
 Get global definitions.
void openTraceContainer (const LocationGroup &locGroup)
 Open trace data container.
void closeTraceContainer ()
 Close trace data container.
LocalTracegetTrace (const GlobalDefs &defs, const Location &location)
 Get trace data.

Static Public Member Functions

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

Constructors & destructor

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

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.

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

      archive->closeTraceContainer();
      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

virtual pearl::TraceArchive::~TraceArchive ( ) [virtual]

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

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

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.
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

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

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
LocalTrace* pearl::TraceArchive::getTrace ( const GlobalDefs defs,
const Location location 
)

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 global definitions object defs, retrieved by a previous call to getDefinitions(). 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.
Parameters:
defsGlobal definitions object
locationLocation whose trace data should be read
Returns:
Pointer to trace data object
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

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:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

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