FilterChain Class Reference

Class that manages a list of filters. More...

#include <FilterChain.h>

Collaboration diagram for FilterChain:

Public Member Functions
virtual void	showArguments (std::ostream &os)
	Display valid command line arguments for filters in the chain.
virtual bool	parseArguments (int &argc, char **argv)
	Permits filters in the chain to process command line arguments.
virtual int	initialize ()
	Initializes all the filters in the chain.
virtual void	finalize ()
	Finalizes all the filters in the chain.
virtual bool	addFilter (Filter *filter)
	Add the given filter to the filter chain.
int	applyFilters (const int estIdx)
	Determine whether a given EST passes the filter criterion the analyzer should perform core (computationally intensive) analysis, according to this filter chain.
void	printStats (std::ostream &os, const int rank) const
	Method to display statistics regarding operation of all the filters in this chain.
Filter *	getFilter (const std::string &name) const
	Method to obtain pointer to a given filter object.
virtual	~FilterChain ()
	The destructor.
Static Public Member Functions
static FilterChain *	setupChain (const char filterStr, ClusterMaker clusterMaker)
	Create the filters in the chain.
static int	applyFilters (ClusterMaker *clusterMaker)
	Main helper method that applies all filters in a distributed manner.
static FilterChain *	getFilterChain ()
	Get a pointer to the instance of the filter chain.
Protected Attributes
std::vector< Filter * >	chain
	The vector containing a list of filters in the chain.
Private Member Functions
	FilterChain ()
	The constructor.
Static Private Member Functions
static void	getOwnedESTidx (int &startIndex, int &endIndex)
	Helper method to compute the start and ending indexes of the EST that this process owns.
static void	allToAllBroadcast (ClusterMaker *clusterMaker)
	Helper method to perform all-to-all broadcast operation.
Static Private Attributes
static FilterChain *	ptrInstance = NULL
	The pointer to the singleton instance of this class.

Detailed Description

Class that manages a list of filters.

This class represents a list of filters that are used to try and elimintate entries that could potentially deteriorate the quality of clustering generated by PEACE. The filters are run prior to commencement of the core clustering operation. For convenient post-processing analysis the filtered ESTs are gathered in suitable "dummy" clusters to be ignored.

Each filter object in the chain implements a specific type of filteration operation and returns an integer indicating the cluster to which an EST is to be assigned. If the cluster ID is -1, then that indicates that the EST must be subjected to regular clustering operations.

Note that filter processing proceeds in a given order. The first filter in the chain is invoked. If that filter returns a positive cluster ID then rest of the filters are not invoked. On the other hand, if a filter returns -1, then the next filter in the chain is invoked. The process continues until all the filters have been exhausted.

Definition at line 63 of file FilterChain.h.

Constructor & Destructor Documentation

FilterChain::~FilterChain ( ) [virtual]

The destructor.

The destructor frees up all the filters added to this filter chain.

Definition at line 109 of file FilterChain.cpp.

References chain.

FilterChain::FilterChain ( ) [private]

The constructor.

This is made private because the filter chain is a singleton, and should only be instantiated from the FilterChain::getFilterChain() static method.

Definition at line 116 of file FilterChain.cpp.

Referenced by setupChain().

Member Function Documentation

bool FilterChain::addFilter ( Filter * filter ) [virtual]

Add the given filter to the filter chain.

This method permits the filter chain to takes ownership of a given filter object by added it to its internal chain.

Note:: The filter chain takes ownership of the object therefore that the filter pointer passed to this method must not be deleted by the caller.

Parameters:

[in] filter The instance of class Filter that should be added to the filter chain.

Returns:: This method returns true if the filter was successfully added. On errors this method returns false.

Definition at line 69 of file FilterChain.cpp.

References ASSERT, and chain.

Referenced by setupChain().

void FilterChain::allToAllBroadcast ( ClusterMaker * clusterMaker ) [static, private]

Helper method to perform all-to-all broadcast operation.

This method is invoked from the applyFilters() (static method) to broadcast the results from filtering out data to all other processes. In addition, this method also receives broadcasts from other processes and applies their filtered results to the local copy. This process ensures that all the processes in the system have a consistent snapshot of the filtered out ESTs.

Note:: Possibly this method (which has a loop) can be replaced by a single MPI all-to-all broadcast call but at expense of increased memory footprint.

Parameters:

[in] clusterMaker The cluster maker to be used for merging the filter data received from other processes.

Definition at line 246 of file FilterChain.cpp.

References ASSERT, chain, MPI_BCAST, MPI_GET_RANK, MPI_GET_SIZE, Filter::processFilterData(), and ptrInstance.

Referenced by applyFilters().

int FilterChain::applyFilters ( const int estIdx ) [inline]

Determine whether a given EST passes the filter criterion the analyzer should perform core (computationally intensive) analysis, according to this filter chain.

This method can be used to compare a given EST with the reference EST (set via the call to the setReferenceEST()) method.

Parameters:

[in] estIdx The index (zero based) of the EST with which the reference EST is to be compared.

Returns:: This method returns the logical cluster to which the given EST must be added since one of the filters flagged it as being an EST to be ignored from the main clustering. If the EST is to be processed as part of the regular clustering process then this method returns -1.

Definition at line 233 of file FilterChain.h.

References chain.

int FilterChain::applyFilters ( ClusterMaker * clusterMaker ) [static]

Main helper method that applies all filters in a distributed manner.

This method is a convinence method that has been introduced here to facilitate the process of applying all filters in a distributed manner. This method operates as follows:

First it initializes all the filters. If initialization fails then this method immediately exits with an non-zero error code.
Next it computes the sub-set of ESTs that this filter is expected to operate on and applies the filters to all the ESTs within the range it owns.
It participates in interative broadcast in which it receives filter data from other processes (if any) and broadcasts its data to others. This process ensures that all processes have a consistent view of the entries that have been filtered out on other processes.
Then it finalizes all the filters.
If all the operations were successfully completed, then this method returns 0 (zero).

Parameters:

[in] clusterMaker The cluster maker to be used for merging the filter data received from other processes.

Returns:: This method returns 0 (zero) on success. On errors it returns a non-zero error code.

Definition at line 206 of file FilterChain.cpp.

References allToAllBroadcast(), applyFilters(), ASSERT, finalize(), EST::getEST(), EST::getESTCount(), getOwnedESTidx(), EST::hasBeenProcessed(), initialize(), MPI_GET_SIZE, and ptrInstance.

Referenced by applyFilters(), and applyFilters().

void FilterChain::finalize ( ) [virtual]

Finalizes all the filters in the chain.

This method iterates over all the filters that have been added ot this chain and calls Filter::finalize() method on each one of them. The finalize operation permits the filters to wrap up their operation and perform any cleanups.

Definition at line 91 of file FilterChain.cpp.

References chain.

Referenced by applyFilters().

Filter * FilterChain::getFilter ( const std::string & name ) const

Method to obtain pointer to a given filter object.

This method can be used to obtain a pointer to a specific filter class present in this chain. If the filter does not exist then this method returns NULL.

Note:: The caller must not delete the returned pointer.

Parameters:

[in] name The name associated with a given filter.

Returns:: If the filter was found then this method returns a valid (non-NULL) pointer to the filter object. If the filter was not found, then this method returns NULL.

Definition at line 98 of file FilterChain.cpp.

References chain.

static FilterChain* FilterChain::getFilterChain ( ) [inline, static]

Get a pointer to the instance of the filter chain.

Since this class is a singleton, the constructor is private and the only way to obtain an instance of the class is through this method. The filter chain is available only after the setupChain method (that is invoked from main right after command line arguments are validated) has successfully completed its operation. Until such time this method simply returns NULL.

Returns:: The process-wide unique pointer to the filter chain.

Definition at line 138 of file FilterChain.h.

References ptrInstance.

void FilterChain::getOwnedESTidx	(	int &	startIndex,
		int &	endIndex
	)			`[static, private]`

Helper method to compute the start and ending indexes of the EST that this process owns.

This method was introduced to keep the math and logic clutter involved in computing the list of owned ESTs out of the methods that use the information. This method returns the range, such that: startIndex <= ownedESTidx < endIndex.

Note:: This method must be invoked only after MPI::Intialize() has beeen called and the ESTs to be processed have be loaded (so that EST::getESTList() returns a valid list of ESTs).

Parameters:

`[out]`	startIndex	The starting (zero-based) index value of the contiguous range of ESTs that this process owns.
`[out]`	endIndex	The ending (zero-based) index value of the contiguous range ESTs that this process owns. The value returned in this parameter is not included in the range of values.

Note:: Currently, this method has exact implementation as in MSTClusterMaker::getOwnedESTidx. This method has been copy-pasted so that filters can operate on their own different sub-set of ESTs if they choose. Maybe the method can be combined together.

Definition at line 173 of file FilterChain.cpp.

References EST::getESTList(), MPI_GET_RANK, and MPI_GET_SIZE.

Referenced by applyFilters().

int FilterChain::initialize ( ) [virtual]

Initializes all the filters in the chain.

This method iterates over all the filters that have been added ot this chain and calls initialize() on each one of them. If any one of the filters are unable to initialize correctly, then this method immediately returns an non-zero error code.

Returns:: This method returns zero on success. On errors this method returns a non-zero value.

Definition at line 77 of file FilterChain.cpp.

References chain, and NO_ERROR.

Referenced by applyFilters().

bool FilterChain::parseArguments	(	int &	argc,
		char **	argv
	)			`[virtual]`

Permits filters in the chain to process command line arguments.

This method iterates over the filters that have been added to this chain and invokes parseArguments() method on each one of them. This permits each filter in the chain to receive and process command line parameters targeted for the filters.

Parameters:

`[in,out]`	argc	The number of command line arguments currently present in argv (the parameter list). This parameter is updated when parameters are consumed.
`[in,out]`	argv	The list of command line arguments to be consumed by various filters, if they find parameters intended for their use. This parameter is updated when command line arguments are consumed by one of the filters.

Returns:: This method returns true if all the filters in the chain successfully processed command line arguments. If an incorrect command line argument is received by any one of the filters then this method returns false to flag an error.

Definition at line 58 of file FilterChain.cpp.

References chain.

Referenced by main().

void FilterChain::printStats	(	std::ostream &	os,
		const int	rank
	)			const

Method to display statistics regarding operation of all the filters in this chain.

This method can be used to obtain a dump of the statistics gathered regarding the operation of all the filters in this chain. The typical statistic generated by filters includes:

The number of times the filter was called. More specifically this value indicates the number of times the applyFilter() method was invoked on a given filter.
The number of ESTs that were permitted to pass through the filter.

Parameters:

`[out]`	os	The output stream to which the statistics regarding the filters is to be dumped.
`[in]`	rank	The rank of the process for which the statistics is being displayed. This value is used to make the outputs a bit more informative.

Definition at line 121 of file FilterChain.cpp.

References chain.

Referenced by main().

FilterChain * FilterChain::setupChain	(	const char *	filterStr,
		ClusterMaker *	clusterMaker
	)			`[static]`

Create the filters in the chain.

This method must be used to establish the chain of filters. This method is typically invoked from the main method. This method parses the names of the filter specified in the parameter filterStr and instantiates suitable filters via the FilterFactory.

Parameters:

`[in]`	filterStr	A string containing the list of filters to be created in this chain. This string is typically specified by the user as a command line parameter. If this parameter is `NULL`, then this method performs no specific action.
`[in]`	clusterMaker	The top-level cluster maker that has been specified by the user. The cluster maker encapsulates the EST analyzer object specified by the user. The filters can use the clusterMaker to perform any special processing they may need.

Definition at line 131 of file FilterChain.cpp.

References addFilter(), ASSERT, FilterFactory::create(), FilterChain(), and ptrInstance.

Referenced by main().

void FilterChain::showArguments ( std::ostream & os ) [virtual]

Display valid command line arguments for filters in the chain.

This method simply calls the showArguments method on each filter in the chain.

Parameters:

[out] os The output stream to which the valid command line arguments must be written.

Definition at line 51 of file FilterChain.cpp.

References chain.

Referenced by showUsage().

Member Data Documentation

std::vector<Filter*> FilterChain::chain [protected]

The vector containing a list of filters in the chain.

This vector contains the list of hueristics assocaited with this chain. Filters are added to the list via the addFilter() method. The filters are used by the shouldAnalyze() method.

Definition at line 305 of file FilterChain.h.

Referenced by addFilter(), allToAllBroadcast(), applyFilters(), finalize(), getFilter(), initialize(), parseArguments(), printStats(), showArguments(), and ~FilterChain().

FilterChain * FilterChain::ptrInstance = NULL [static, private]

The pointer to the singleton instance of this class.

Again, this is made private so that only methods of this class can access it. The getFilterChain() method in this class must be used to obtain an instance of this class.

Definition at line 322 of file FilterChain.h.

Referenced by allToAllBroadcast(), applyFilters(), getFilterChain(), and setupChain().

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

FilterChain Class Reference

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation