Tool Class Reference

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

#include <Tool.hpp>

Inheritance diagram for Tool:

Public Member Functions
	Tool (const std::string &name)
virtual	~Tool ()
std::string	getName () const
virtual IProperties *	run (IProperties *input)
virtual IProperties *	run (int argc, char *argv[])
virtual void	execute ()=0
virtual IProperties *	getInput ()
virtual IProperties *	getOutput ()
virtual IProperties *	getInfo ()
virtual IOptionsParser *	getParser ()
virtual dp::IDispatcher *	getDispatcher ()
virtual TimeInfo &	getTimeInfo ()
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::IteratorListener *	createIteratorListener (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
#include <gatb/gatb_core.hpp>

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]

name

name 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:

• /builds/workspace/publish-doc-api-gitlab/gatb-core/src/gatb/tools/misc/impl/Tool.hpp
• /builds/workspace/publish-doc-api-gitlab/gatb-core/src/gatb/tools/misc/impl/Tool.cpp