gatb.core-API-1.4.2
Tool Class Referenceabstract

Framework abstract class for implementing tools (ie. binary tools). More...

#include <Tool.hpp>

Inheritance diagram for Tool:
Inheritance graph

Public Member Functions

 Tool (const std::string &name)
 
virtual ~Tool ()
 
std::string getName () const
 
virtual IPropertiesrun (IProperties *input)
 
virtual IPropertiesrun (int argc, char *argv[])
 
virtual void execute ()=0
 
virtual IPropertiesgetInput ()
 
virtual IPropertiesgetOutput ()
 
virtual IPropertiesgetInfo ()
 
virtual IOptionsParsergetParser ()
 
virtual dp::IDispatchergetDispatcher ()
 
virtual TimeInfogetTimeInfo ()
 
template<typename Item >
dp::Iterator< Item > * createIterator (collections::Iterable< Item > &iterable, const char *message=0)
 
template<typename Item >
dp::Iterator< Item > * createIterator (dp::Iterator< Item > *iter, size_t nbIterations=0, const char *message=0)
 
virtual dp::IteratorListenercreateIteratorListener (size_t nbIterations, const char *message)
 
virtual void displayVersion (std::ostream &os)
 
- Public Member Functions inherited from SmartPointer
void use ()
 
void forget ()
 
- Public Member Functions inherited from ISmartPointer
virtual ~ISmartPointer ()
 

Protected Member Functions

std::string getUriByKey (const std::string &key)
 
std::string getUri (const std::string &str)
 
void setInput (IProperties *input)
 
- Protected Member Functions inherited from SmartPointer
 SmartPointer ()
 
virtual ~SmartPointer ()
 

Protected Attributes

std::string _name
 

Detailed Description

Framework abstract class for implementing tools (ie. binary tools).

This class provides facilities for:

  • parsing command line
  • dispatching work on several threads
  • getting execution times
  • gathering statistics information

The Tool sub classes must implement the execute method; this is the place where the actual job of the tool has to be done.

If the tool is launch with the run method and the famous [argc,argv] couple, the command line [argc,argv] is parsed through an options parser and the recognized options are available through the getInput method.

The option parser should be configured (ie. adding specific options) during the constructor of the Tool sub class. By default, some default options are attached to the Tool options parser; for instance :

  • "-nb-cores" is available and enables to set the number of cores that can be used by the tool.
  • "-verbose" is available and can be used for having progress bar while iterating iterators.

A dispatcher is available with the getDispatcher method. This dispatcher may have been configured (ie. set the number of available cores) during the constructor.

Example:

// We include what we need for the test
using namespace std;
/********************************************************************************/
/* Using Tool class for quick tool development. */
/********************************************************************************/
// We define some constant strings for names of command line parameters
static const char* STR_RANGE_MIN = "-min";
static const char* STR_RANGE_MAX = "-max";
/********************************************************************************/
// We define our own tool as a class that inherits from the Tool class
// By doing this, we will get:
// - a command line parser with default options; we will add specific options
// - a mean to retrieve command line options values in our code
// - a mean to get configurable progression bar for our ongoing job
// - a dispatcher object for easy multi-threading
// - a mean to get time execution information
// - a mean to gather any piece of information for output
// - a mean to run the tool in the 'main' function
class ToyTool : public Tool
{
public:
// The Tool constructor allows to give a name to our tool.
// This name appears when one gets help in the command line or in the final output
ToyTool () : Tool ("ToyTool")
{
// By default, the Tool class provides 3 default command line arguments:
// "-nb-cores X" : number of cores used by the dispatcher object (0 means all cores)
// "-verbose X" : verbosity level (0: none, 1 and 2: bargraphs and final output)
// "-help" : just dump help about the tool
// Now, we add two custom command line arguments with the parser we got from Tool
// the "-min" argument is not mandatory, with default value 1
// the "-max" argument is mandatory
getParser()->push_front (new OptionOneParam (STR_RANGE_MIN, "lower range bound", false, "1"));
getParser()->push_front (new OptionOneParam (STR_RANGE_MAX, "upper range bound", true));
// Hence our tool can get 5 arguments as input (3 default, 2 custom)
// One can get them by using "./ToyTool -help"
// Note: if the mandatory argument is not provided, an error is dumped in console
}
// The 'execute' method must be implemented as we are a subclass of Tool
// This method does the actual job our tool is supposed to do (here some dummy computation)
void execute ()
{
// Our job is to compute some dummy information from integers in an range.
// This range is configured with our two command line arguments.
// Here, we see how to retrieve the arguments values through the 'getInput' method
Range<u_int64_t> range (
getInput()->getInt(STR_RANGE_MIN),
getInput()->getInt(STR_RANGE_MAX)
);
// We create an iterator over our integer range.
// Note how we use the Tool::createIterator method. According to the value of the "-verbose" argument,
// this method will add some progression bar if needed.
Iterator<u_int64_t>* iter = createIterator<u_int64_t> (range, "iterate range");
LOCAL (iter);
// We will do some dummy computation
u_int64_t totalSum = 0;
// We want to get execution time. We use the Tool::getTimeInfo() method for this.
getTimeInfo().start ("computation");
// We iterate the range through the Dispatcher we got from our Tool parent class.
// The dispatcher is configured with the number of cores provided by the "-nb-cores" command line argument.
IDispatcher::Status status = getDispatcher()->iterate (iter, [&] (const u_int64_t& i)
{
// We do some dummy computation.
u_int64_t sum = 0;
for (u_int64_t j=0; j<i; j++) { sum += j; }
__sync_fetch_and_add (&totalSum, sum);
});
getTimeInfo().stop ("computation");
// We gather some statistics. Note how we use the getInfo() method from the parent class Tool
// If the verbosity is not 0, all this information will be dumped in the console at the end
// of the tool execution
getInfo()->add (1, "output");
getInfo()->add (2, "sum", "%ld", totalSum);
getInfo()->add (1, getTimeInfo().getProperties("time"));
}
};
/********************************************************************************/
// Once our tool class is defined, we can run it in the main function of the program.
int main (int argc, char* argv[])
{
// We use a try/catch block since GATB functions may throw exceptions
try
{
// We run our tool with the provided command line arguments.
// This will call the ToyTool::execute method we have defined.
ToyTool().run (argc, argv);
// You can try to launch our tool with different command line arguments.
// For instance, you can try different number of threads:
// ./ToyTool -max 200000 -nb-cores 1
// ./ToyTool -max 200000 -nb-cores 2
// ./ToyTool -max 200000 -nb-cores 4
// ./ToyTool -max 200000 -nb-cores 8
}
catch (Exception& e)
{
std::cout << "EXCEPTION: " << e.getMessage() << std::endl;
return EXIT_FAILURE;
}
}
See also
Algorithm

Constructor & Destructor Documentation

Tool ( const std::string &  name)

Constructor.

Parameters
[in]namename of the tool.
~Tool ( )
virtual

Destructor.

Member Function Documentation

dp::Iterator<Item>* createIterator ( collections::Iterable< Item > &  iterable,
const char *  message = 0 
)
inline

Create an iterator for the given iterable. If the verbosity is enough, progress bar information can be displayed.

Parameters
[in]iterable: object that creates the iterator.
[in]message: message used if progress information has to be displayed
Returns
the created iterator.
dp::Iterator<Item>* createIterator ( dp::Iterator< Item > *  iter,
size_t  nbIterations = 0,
const char *  message = 0 
)
inline

Create an iterator for the given iterator. If the verbosity is enough, progress bar information can be displayed.

Parameters
[in]iter: object to be encapsulated by a potential progress information
[in]nbIterations: number of iterations to be done.
[in]message: message used if progress information has to be displayed
Returns
the created iterator.
dp::IteratorListener * createIteratorListener ( size_t  nbIterations,
const char *  message 
)
virtual

Creates an iterator listener according to the verbosity level.

Parameters
[in]nbIterations: number of iterations to be done
[in]message: progression message
Returns
an iterator listener.
void displayVersion ( std::ostream &  os)
virtual

Displays information about the GATB library

Parameters
[in]os: output stream used for dumping library information
virtual void execute ( )
pure virtual

Subclasses must implement this method; this is where the actual job of the tool has to be done.

virtual dp::IDispatcher* getDispatcher ( )
inlinevirtual

Get a dispatched that can be used for parallelization. The option "-nb-cores" can be used, and thus the provided number is used for configuring the dispatcher.

Returns
the dispatcher for the tool
virtual IProperties* getInfo ( )
inlinevirtual

Get statistics information about the execution of the tool

Returns
the statistics
virtual IProperties* getInput ( )
inlinevirtual

Get the parsed options as a properties instance

Returns
the parsed options.
std::string getName ( ) const
inline

Get tool name

Returns
the tool name.
virtual IProperties* getOutput ( )
inlinevirtual

Get output results as a properties instance

Returns
the output results
virtual IOptionsParser* getParser ( )
inlinevirtual

Get an option parser configured with recognized options for the tool

Returns
the options parser instance
virtual TimeInfo& getTimeInfo ( )
inlinevirtual

Get a TimeInfo instance for the tool. This object can be used for gathering execution times of some parts of the execute method.

Returns
the time info instance.
std::string getUri ( const std::string &  str)
inlineprotected

Computes the uri from an uri (ie add a prefix if any).

std::string getUriByKey ( const std::string &  key)
inlineprotected

Computes the uri from an uri (ie add a prefix if any).

IProperties * run ( IProperties input)
virtual

Run the tool with input parameters provided as a IProperties instance

Parameters
[in]input: input parameters
Returns
the parsed options as a IProperties instance
IProperties * run ( int  argc,
char *  argv[] 
)
virtual

Run the tool with input parameters provided as a couple [argc,argv]

Parameters
[in]argc: number of arguments
[in]argv: array of arguments
Returns
the parsed options as a IProperties instance
void setInput ( IProperties input)
inlineprotected

Setters.

Member Data Documentation

std::string _name
protected

Name of the tool (set at construction).


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