CachedPager Class Reference
[Plug-In Shells]

This class represents provides cached access to pages. More...

#include <CachedPager.h>

Inheritance diagram for CachedPager:

List of all members.

Public Member Functions

CachedPager ()

CachedPager (const size_t cacheSize)

~CachedPager ()

bool getInputSpecification (PlugInArgList *&pArgList)

bool getOutputSpecification (PlugInArgList *&pArgList)

bool execute (PlugInArgList *pInputArgList, PlugInArgList *pOutputArgList)

virtual bool parseInputArgs (PlugInArgList *pInputArgList)

RasterPage * getPage (DataRequest *pOriginalRequest, DimensionDescriptor startRow, DimensionDescriptor startColumn, DimensionDescriptor startBand)

void releasePage (RasterPage *pPage)

int getSupportedRequestVersion () const

Static Public Member Functions

static std::string PagedElementArg ()

static std::string PagedFilenameArg ()

Protected Member Functions

const int getBytesPerBand () const

const int getColumnCount () const

const int getBandCount () const

const RasterElement * getRasterElement () const

virtual double getChunkSize () const

Detailed Description

This class represents provides cached access to pages.

By 'cached', we mean that a block may be indexed into by multiple data accessors (ie. multithreading an algorithm to function with 2 threads, each reading odd and even rows). developers would take this class and extend it to support their algorithm specific code.

Definition at line 39 of file CachedPager.h.

Constructor & Destructor Documentation

CachedPager::CachedPager ( )

Creates a CachedPager PlugIn.

Sets cache size to 10 MB. Sets writable flag to false.

Subclasses need to override private pure virtual methods to open the file and get a block from that file.

CachedPager::CachedPager ( const size_t cacheSize )

Creates a CachedPager PlugIn.

Sets cache size to cacheSize bytes. Sets writable flag to false.

Subclasses need to override private pure virtual methods to open the file and get a block from that file.

Parameters:

cacheSize

Number of bytes in the page cache.

CachedPager::~CachedPager ( )

Destructor.

Member Function Documentation

static std::string CachedPager::PagedElementArg ( ) [static]

The name to use for the raster element argument.

This argument should be populated with the RasterElement that this object will page. Arguments with this name should be of the type RasterElement.

Definition at line 49 of file CachedPager.h.

static std::string CachedPager::PagedFilenameArg ( ) [static]

The name to use for the filename argument.

This argument should be populated with the Filename that this object will page. Arguments with this name should be of the type Filename.

Definition at line 61 of file CachedPager.h.

bool CachedPager::getInputSpecification ( PlugInArgList *& pArgList ) [virtual]

Get Plug-In Input Specification.

The getInputSpecification() method is used by the Plug-In Manager to determine the input parameters to generically execute the Plug-In.

Parameters:

pArgList

Returns a pointer to a PlugInArgList specifying the the Plug-In input parameters.

Returns:: This method returns true if the input parameter argument list was successfully created.

Implements Executable.

Reimplemented in HdfPager.

bool CachedPager::getOutputSpecification ( PlugInArgList *& pArgList ) [virtual]

Get Plug-In Output Specification.

The getOutputSpecification() method is used by the Plug-In Manager to determine the output parameters of the generically executed the Plug-In.

Parameters:

pArgList

Returns a pointer to a PlugInArgList specifying the the Plug-In output parameters.

Returns:: This method returns true if the output parameter argument list was successfully created.

Reimplemented from RasterPagerShell.

bool CachedPager::execute	(	PlugInArgList *	pInputArgList,
		PlugInArgList *	pOutputArgList
	)			`[virtual]`

Executes the plug-in.

Parameters:

	pInputArgList	On input, pInputArgList contains a complete input argument list for the plug-in. On return, this argument list may be updated to reflect changes made by the plug-in.
	pOutputArgList	On input, pOutputArgList contains a complete output argument list for the plug-in, although actual values and default values will be ignored. On return, this argument list will be updated to indicate all output parameters made by the plug-in.

Returns:: True if the execution was successful. False is returned if the user cancelled the plug-in while in interactive mode.

Implements Executable.

virtual bool CachedPager::parseInputArgs ( PlugInArgList * pInputArgList ) [virtual]

Parses PlugInArgList pInputArgList.

Assigns values from the input argument list to member variables for use during execute.

Parameters:

pInputArgList

The input argument list to parse. Should not be NULL.

Returns:: TRUE if the operation succeeds; FALSE if pInputArgList is NULL or if the operation fails.

Reimplemented in HdfPager.

RasterPage* CachedPager::getPage	(	DataRequest *	pOriginalRequest,
		DimensionDescriptor	startRow,
		DimensionDescriptor	startColumn,
		DimensionDescriptor	startBand
	)			`[virtual]`

This method should return a CachedPage (which inherits RasterPage) interface that will allow access to an in memory pointer of the requested data that has been loaded from the original file on disk.

The in memory pointer should point to a section of memory that adheres to the following constraints:

The memory pointer should point to raw cube data that is either formatted as specified in the pOriginalRequest parameter.
The memory pointer should point to raw cube data where each pixel value is RasterDataDescriptor::getBytesPerElement() large. The DataDescriptor object should be retrieved from the RasterElement that this RasterPager is associated with.
The memory pointer should point to raw cube data where there are only post-line bytes. If there are post-line bytes, they should be equal to DatasetParameters::getPostlineBytes() The DatasetParameters object should be retrieved from the RasterElement that this RasterPager is associated with.
The memory pointer should point to raw cube data that contains at minimum concurrentRows, concurrentBands, concurrentColumns worth of data that is directly acccessible in memory.

This method may be called simultaneously by multiple threads and is up to the implementer of this method to guarantee thread-safety in that case.

Parameters:

	pOriginalRequest	The request as originally made. The fields on this object should be examined to determine if this pager can handle the request, and how to format it. Use the other parameters to this method to determine where to start the RasterPage.
	startRow	the start row of data that should be loaded from the original data file on disk into memory.
	startColumn	the start column of data that should be loaded from the original data file on disk into memory.
	startBand	the start band of data that should be loaded from the original data file on disk into memory.

Returns:: a RasterPage object, that when the getRawData() pointer is called will return a pointer to the requested cube data. This RasterPage object should not be directly deleted, but should be passed to the releasePage() method below when the RasterPage is no longer needed.

If the request cannot be fulfilled, return NULL.

Implements RasterPager.

void CachedPager::releasePage ( RasterPage * pPage ) [virtual]

This method will release the RasterPage* that was requested earlier via the getPage() method.

NOTE: This method will check to ensure that the RasterPage is a CachedPage prior to removal and deletion.

This method should only release those RasterPage* that were returned by the getPage() method of the same instance of the RasterPager. This method may be called simultaneously by multiple threads and is up to the implementer of this method to guarantee thread-safety in that case.

Parameters:

pPage

the RasterPage that should be released.

Implements RasterPager.

int CachedPager::getSupportedRequestVersion ( ) const [virtual]

Get the highest version of DataRequest that this pager supports.

RasterPagers can support a variety of conversions from the native data to that request in a DataRequest. getPage() should be implemented to check for these conversions and return NULL if unsupported.

As features are added, additional fields may be added to DataRequest. The defaults for these fields will always be the same as on the RasterElement being accessed. Since these fields may be added without breaking compatibility with existing RasterPager plug-ins, there will be existing plug-ins which do not know to check these new fields and return NULL if unsupported.

Return a value here to state what version of DataRequest is supported. If any higher-version fields are changed from the defaults, the core will assume that the RasterPager is unable to handle them, and the request will not be fulfilled.

Returns:: The highest request version supported.

See also:: DataRequest::getRequestVersion()

Implements RasterPager.

const int CachedPager::getBytesPerBand ( ) const [protected]

Accessor function for subclasses to gain access to private member variables.

Returns:: The number of bytes in a single element of data. For a 200 row x 100 column x 10 band x INT2UBYTES dataset, this function would return 2.

const int CachedPager::getColumnCount ( ) const [protected]

Accessor function for subclasses to gain access to private member variables.

Returns:: The number of columns in the dataset.

const int CachedPager::getBandCount ( ) const [protected]

Accessor function for subclasses to gain access to private member variables.

Returns:: The number of bands in the dataset.

const RasterElement* CachedPager::getRasterElement ( ) const [protected]

Accessor function for subclasses to gain access to private member variables.

Returns:: A pointer to the RasterElement.

virtual double CachedPager::getChunkSize ( ) const [protected, virtual]

Returns a reasonable chunk size.

Reasonable chunk sizes are important in keeping performance high, since reading row by row could be as small as 16KB at a time (ie 2 bytes x 1024 columns x 8 bands) and would not optimize for IO. Instead, the CachedPager uses chunk sizes to read in X MB of whole rows (including bands if BIP).

Returns:: A reasonable chunk size, in bytes. Default implementation returns 1048576 bytes (1 MB).


Public Member Functions
	CachedPager ()
	CachedPager (const size_t cacheSize)
	~CachedPager ()
bool	getInputSpecification (PlugInArgList *&pArgList)
bool	getOutputSpecification (PlugInArgList *&pArgList)
bool	execute (PlugInArgList pInputArgList, PlugInArgList pOutputArgList)
virtual bool	parseInputArgs (PlugInArgList *pInputArgList)
RasterPage *	getPage (DataRequest *pOriginalRequest, DimensionDescriptor startRow, DimensionDescriptor startColumn, DimensionDescriptor startBand)
void	releasePage (RasterPage *pPage)
int	getSupportedRequestVersion () const
Static Public Member Functions
static std::string	PagedElementArg ()
static std::string	PagedFilenameArg ()
Protected Member Functions
const int	getBytesPerBand () const
const int	getColumnCount () const
const int	getBandCount () const
const RasterElement *	getRasterElement () const
virtual double	getChunkSize () const

CachedPager Class Reference [Plug-In Shells]

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

CachedPager Class Reference
[Plug-In Shells]