DynamoRIO API
analysis_tool_t Class Referenceabstract

#include <analysis_tool.h>

Public Member Functions

 analysis_tool_t ()
 
virtual std::string initialize ()
 
virtual bool operator! ()
 
virtual std::string get_error_string ()
 
virtual bool process_memref (const memref_t &memref)=0
 
virtual bool print_results ()=0
 
virtual bool parallel_shard_supported ()
 
virtual void * parallel_worker_init (int worker_index)
 
virtual std::string parallel_worker_exit (void *worker_data)
 
virtual void * parallel_shard_init (int shard_index, void *worker_data)
 
virtual bool parallel_shard_exit (void *shard_data)
 
virtual bool parallel_shard_memref (void *shard_data, const memref_t &memref)
 
virtual std::string parallel_shard_error (void *shard_data)
 
 analysis_tool_t ()
 
virtual std::string initialize ()
 
virtual bool operator! ()
 
virtual std::string get_error_string ()
 
virtual bool process_memref (const memref_t &memref)=0
 
virtual bool print_results ()=0
 
virtual bool parallel_shard_supported ()
 
virtual void * parallel_worker_init (int worker_index)
 
virtual std::string parallel_worker_exit (void *worker_data)
 
virtual void * parallel_shard_init (int shard_index, void *worker_data)
 
virtual bool parallel_shard_exit (void *shard_data)
 
virtual bool parallel_shard_memref (void *shard_data, const memref_t &memref)
 
virtual std::string parallel_shard_error (void *shard_data)
 

Detailed Description

The base class for a tool that analyzes a trace. A new tool should subclass this class.

Concurrent processing of traces is supported by logically splitting a trace into "shards" which are each processed sequentially. The default shard is a traced application thread, but the tool interface can support other divisions. For tools that support concurrent processing of shards and do not need to see a single thread-interleaved merged trace, the interface functions with the parallel_ prefix should be implemented, and parallel_shard_supported() should return true. parallel_shard_init() will be invoked for each shard prior to invoking parallel_shard_memref() for any entry in that shard; the data structure returned from parallel_shard_init() will be passed to parallel_shard_memref() for each trace entry for that shard. The concurrency model used guarantees that all entries from any one shard are processed by the same single worker thread, so no synchronization is needed inside the parallel_ functions. A single worker thread invokes print_results() as well.

For serial operation, process_memref(), operates on a trace entry in a single, sorted, interleaved stream of trace entries. In the default mode of operation, the analyzer_t class iterates over the trace and calls the process_memref() function of each tool. An alternative mode is supported which exposes the iterator and allows a separate control infrastructure to be built. This alternative mode does not support parallel operation at this time.

Both parallel and serial operation can be supported by a tool, typically by having process_memref() create data on a newly seen traced thread and invoking parallel_shard_memref() to do its work.

For both parallel and serial operation, the function print_results() should be overridden. It is called just once after processing all trace data and it should present the results of the analysis. For parallel operation, any desired aggregation across the whole trace should occur here as well, while shard-specific results can be presented in parallel_shard_exit().

Constructor & Destructor Documentation

analysis_tool_t::analysis_tool_t ( )
inline

Errors encountered during the constructor will set the success flag, which should be queried via operator!. On an error, get_error_string() provides a descriptive error message.

analysis_tool_t::analysis_tool_t ( )
inline

Errors encountered during the constructor will set the success flag, which should be queried via operator!. On an error, get_error_string() provides a descriptive error message.

Member Function Documentation

virtual std::string analysis_tool_t::get_error_string ( )
inlinevirtual

Returns a description of the last error.

virtual std::string analysis_tool_t::get_error_string ( )
inlinevirtual

Returns a description of the last error.

virtual std::string analysis_tool_t::initialize ( )
inlinevirtual

Destructor. Tools are encouraged to perform any initialization that might fail here rather than in the constructor. On an error, this returns an error string. On success, it returns "".

virtual std::string analysis_tool_t::initialize ( )
inlinevirtual

Destructor. Tools are encouraged to perform any initialization that might fail here rather than in the constructor. On an error, this returns an error string. On success, it returns "".

virtual bool analysis_tool_t::operator! ( )
inlinevirtual

Returns whether the tool was created successfully.

virtual bool analysis_tool_t::operator! ( )
inlinevirtual

Returns whether the tool was created successfully.

virtual std::string analysis_tool_t::parallel_shard_error ( void *  shard_data)
inlinevirtual

Returns a description of the last error for this shard.

virtual std::string analysis_tool_t::parallel_shard_error ( void *  shard_data)
inlinevirtual

Returns a description of the last error for this shard.

virtual bool analysis_tool_t::parallel_shard_exit ( void *  shard_data)
inlinevirtual

Invoked once when all trace entries for a shard have been processed. shard_data is the value returned by parallel_shard_init() for this shard. This allows a tool to clean up its thread data, or to report thread analysis results. Most tools, however, prefer to aggregate data or at least sort data, and perform nothing here, doing all cleanup in print_results() by storing the thread data into a table. Return whether exiting was successful. On failure, parallel_shard_error() returns a descriptive message.

virtual bool analysis_tool_t::parallel_shard_exit ( void *  shard_data)
inlinevirtual

Invoked once when all trace entries for a shard have been processed. shard_data is the value returned by parallel_shard_init() for this shard. This allows a tool to clean up its thread data, or to report thread analysis results. Most tools, however, prefer to aggregate data or at least sort data, and perform nothing here, doing all cleanup in print_results() by storing the thread data into a table. Return whether exiting was successful. On failure, parallel_shard_error() returns a descriptive message.

virtual void* analysis_tool_t::parallel_shard_init ( int  shard_index,
void *  worker_data 
)
inlinevirtual

Invoked once for each trace shard prior to calling parallel_shard_memref() for that shard, this allows a tool to create data local to a shard. The shard_index is a unique identifier allowing shard data to be stored into a global table if desired (typically for aggregation use in print_results()). The worker_data is the return value of parallel_worker_init() for the worker thread who will exclusively operate on this shard. The return value here will be passed to each invocation of parallel_shard_memref() for that same shard.

virtual void* analysis_tool_t::parallel_shard_init ( int  shard_index,
void *  worker_data 
)
inlinevirtual

Invoked once for each trace shard prior to calling parallel_shard_memref() for that shard, this allows a tool to create data local to a shard. The shard_index is a unique identifier allowing shard data to be stored into a global table if desired (typically for aggregation use in print_results()). The worker_data is the return value of parallel_worker_init() for the worker thread who will exclusively operate on this shard. The return value here will be passed to each invocation of parallel_shard_memref() for that same shard.

virtual bool analysis_tool_t::parallel_shard_memref ( void *  shard_data,
const memref_t memref 
)
inlinevirtual

The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. The shard_data parameter is the value returned by parallel_shard_init() for this shard. Since each shard is operated upon in its entirety by the same worker thread, no synchronization is needed. The return value indicates whether this function was successful. On failure, parallel_shard_error() returns a descriptive message.

virtual bool analysis_tool_t::parallel_shard_memref ( void *  shard_data,
const memref_t memref 
)
inlinevirtual

The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. The shard_data parameter is the value returned by parallel_shard_init() for this shard. Since each shard is operated upon in its entirety by the same worker thread, no synchronization is needed. The return value indicates whether this function was successful. On failure, parallel_shard_error() returns a descriptive message.

virtual bool analysis_tool_t::parallel_shard_supported ( )
inlinevirtual

Returns whether this tool supports analyzing trace shards concurrently, or whether it needs to see a single thread-interleaved stream of traced events.

virtual bool analysis_tool_t::parallel_shard_supported ( )
inlinevirtual

Returns whether this tool supports analyzing trace shards concurrently, or whether it needs to see a single thread-interleaved stream of traced events.

virtual std::string analysis_tool_t::parallel_worker_exit ( void *  worker_data)
inlinevirtual

Invoked once when a worker thread is finished processing all shard data. The worker_data is the return value of parallel_worker_init(). A non-empty string indicates an error while an empty string indicates success.

virtual std::string analysis_tool_t::parallel_worker_exit ( void *  worker_data)
inlinevirtual

Invoked once when a worker thread is finished processing all shard data. The worker_data is the return value of parallel_worker_init(). A non-empty string indicates an error while an empty string indicates success.

virtual void* analysis_tool_t::parallel_worker_init ( int  worker_index)
inlinevirtual

Invoked once for each worker thread prior to calling any shard routine from that thread. This allows a tool to create data local to a worker, such as a cache of data global to the trace that crosses shards. This data does not need any synchronization as it will only be accessed by this worker thread. The worker_index is a unique identifier for this worker. The return value here will be passed to the invocation of parallel_shard_init() for each shard upon which this worker operates.

virtual void* analysis_tool_t::parallel_worker_init ( int  worker_index)
inlinevirtual

Invoked once for each worker thread prior to calling any shard routine from that thread. This allows a tool to create data local to a worker, such as a cache of data global to the trace that crosses shards. This data does not need any synchronization as it will only be accessed by this worker thread. The worker_index is a unique identifier for this worker. The return value here will be passed to the invocation of parallel_shard_init() for each shard upon which this worker operates.

virtual bool analysis_tool_t::print_results ( )
pure virtual

This routine reports the results of the trace analysis. It should leave the i/o state in a default format (std::dec) to support multiple tools. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.

virtual bool analysis_tool_t::print_results ( )
pure virtual

This routine reports the results of the trace analysis. It should leave the i/o state in a default format (std::dec) to support multiple tools. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.

virtual bool analysis_tool_t::process_memref ( const memref_t memref)
pure virtual

The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. If it prints, it should leave the i/o state in a default format (std::dec) to support multiple tools. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.

virtual bool analysis_tool_t::process_memref ( const memref_t memref)
pure virtual

The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. If it prints, it should leave the i/o state in a default format (std::dec) to support multiple tools. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.


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