#ifndef MxNDataHandle_h_seen
#define MxNDataHandle_h_seen

// We use these AVIs
#include "DistArrayDescriptor.h"

namespace gov {
  namespace cca {

	/* $Id: MxNDataHandle.h,v 1.3 2002/04/08 01:16:08 kohl Exp $ */

	/**
 	 * MxN Parallel Data Redistribution
	 *
	 * Data Handle Object Interface
 	 *
 	 * CCA MxN Working Group
 	 */

	class MxNDataHandle : public virtual gov::cca::Port {
	public:

	/**
	 * MxN Interface
	 *
	 * The purpose of this interface is to allow CCA components to
	 * identify and exchange data elements among parallel, decomposed
	 * data objects.  One parallel component with "M" instances might
	 * want to share or correlate data with another parallel component
	 * with "N" instances.  In some cases M == N, and the data mapping
	 * is straightforward, although M and N could have different data
	 * decompositions which would require remapping the data elements.
	 * In other cases, N == 1, and the parallel data is collected into
	 * a central location, such as for most visualization purposes.
	 * When M != N, then a full "redistribution" of the parallel data
	 * objects is required, to map each element of one data distribution
	 * to a corresponding element in another data distribution.
	 *
	 * There is no implicit support for any data "munging" here,
	 * such as spatial or temporal interpolation or units conversions.
	 * These functions are outside the scope of MxN data exchange
	 * and should be implemented in another interface, likely as a
	 * "filter" service, component or port.
	 *
	 * As the CCA definitions for Data Objects becomes more complete,
	 * this MxN interface should be expected to support a wide variety
	 * of data organizations and decompositions, including both
	 * structured and unstructured meshes.  But for the purposes
	 * of this initial interface description, the "Data Object" is
	 * left open and unspecified.  Ultimately, the MxN interface
	 * will require sufficient information from a given Data Object
	 * interface to be able to:
	 *
	 * 1. Identify the owner/location of any specific data element.
	 *
	 * 2. Extract and Assign the value(s) associated with a specific
	 *     data element.
	 * 
	 * As long as all necessary information is available to support
	 * these operations, then the MxN interface can function.  Such
	 * information includes, but may not be limited to:  pointers to
	 * actual data values, the data type(s), the dimensionality and
	 * cardinality of any arrays, the allocated data size, leading
	 * dimensions and boundary/ghost regions of any locally stored
	 * subarrays, the data layout (as in Row Major or Column Major),
	 * the element ids, coordinates, and vertex displacement of values
	 * for an unstructured mesh, the spatial grid type and mapping,
	 * some instantaneous temporal reference value, the units of the
	 * data values, the processor topology, the decomposition types
	 * along each axis for structured meshes, and the details of each
	 * parallel instance's portion of a data distribution (logical
	 * processor address, block or cycle size for rectangular
	 * decompositions, and any explicit decomposition bounds or
	 * patches).
	 *
	 * Note that some of the information above may be used purely for
	 * error checking and validation purposes in the MxN interface
	 * (e.g. spatial grid and units), but this information will be
	 * essential for *other* support interfaces (such as interpolation
	 * and units conversion) that must be present in any practical
	 * implementation.
	 *
	 * To allow any sharing and exchange of parallel data, each
	 * parallel data object must be registered with an instance of
	 * the MxN implementation - say, an "MxN-er" (which could be a
	 * port on a component or a system service, etc).  Data objects
	 * can be registered by any parallel component that has access
	 * to a given MxN-er.  Once all data objects have been registered,
	 * the MxN-er can support a variety of dynamic MxN interconnections
	 * among the parallel component instances.
	 *
	 * To register a data object with the MxN-er, a parallel component
	 * must describe the data and any distributed decomposition (i.e.
	 * who owns which pieces of it) and also make the actual data
	 * elements themselves available for reading and/or writing as
	 * part of subsequent MxN transfers.  All of this information
	 * about the data objects is currently encapsulated in the MxN
	 * interface using a generic "Data" interface placeholder, while
	 * the actual data interface is under development by the CCA Data
	 * Working Group.  The "registerData()" method takes this data
	 * object information, along with some basic synchronization
	 * and access mode settings, and produces an MxN data handle
	 * for use in constructing MxN connections and transfers (see
	 * MxNDataPort.h).
	 *
	 * This data handle interface allows introspection of the details
	 * of any MxN-registered data object.
	 *
	 * More details of the methods in this interface are described
	 * below.
	 */

	/**
	 * mxnDataHandle Type
	 *
	 * Someday we may need something more here, but for now it's an int.
	 */
	typedef int mxnDataHandle;

	/**
	 * New Methods Will Be:
	 *
	 *	getApplName()
	 *	getDADF()
	 */
	
	/**
	 * int getDataName( char * &name )
	 *
	 * Returns the data field name for the given data handle.
	 * It is assumed that this would be handy for programmatically
	 * determining who you want to connect to via MxN...
	 *
	 * @param name Output the name of the given data field.
	 * @return execution status (0 if OK, !=0 if error)
	 */
	virtual int getDataName( char * &name ) = 0;

	/**
	 * Old Methods...
	 */

	/**
	 * int getDataBounds( int * &upper, int * &lower, int &rank )
	 *
	 * Returns the rank and Global Upper and Lower Bounds for the
	 * data field represented by the given data handle.
	 * It is assumed that this would be handy for creating a local
	 * array that would be amazingly enough the exact size needed
	 * to MxN couple with the given data field (like for VizProxy :-).
	 *
	 * @param upper Output an array of the Global Upper Bounds for data.
	 * @param lower Output an array of the Global Lower Bounds for data.
	 * @param rank Output the size of the upper and lower arrays.
	 * @return execution status (0 if OK, !=0 if error)
	 */
	virtual int getDataBounds( int * &upper, int * &lower,
			int &rank ) = 0;

	}; // MxNDataHandle

  } // namespace cca
} // namespace gov

#endif // MxNDataHandle_h_seen