itaps-parallel [Fwd: dropping iBase_UNDETERMINED]

[Lori A. Diachin]

Reminder - here's one of the issues we'll be discussing during today's 
telecon at 12:30 pacific. 

Lori

-------- Original Message --------
Subject: 	dropping iBase_UNDETERMINED
Date: 	Mon, 16 Feb 2009 10:47:22 -0600
From: 	Jason Kraftcheck <kraftche at cae.wisc.edu>
To: 	TSTT Interface <tstt-interface at mcs.anl.gov>



I have yet another change proposal for simplifying the iMesh and iGeom
interfaces.  I think we should remove the "iBase_UNDETERMINED" value from
the iBase_StorageOrder enum, and make all storage order arguments "in"
rather than "inout" (pass by copy rather than by pointer in C).

The feature that making the argument "inout" is intended to facilitate is
optimization where the application can allow the implementation to choose
the storage order in which it passes back values.  The application sets the
value to iBase_UNDETERMINED and the implementation sets it to whatever
storage order the returned data is in.  I think that:
  a) This feature is unlikely to be used much.
  b) The optimization is somewhat dubious.
  c) Making the argument "inout" is not the simplest way to facilitate
     this feature.
  d) The API will be easier to use for the vast majority of codes that
     do not utilize this optimization if the argument is "in".
  e) The API will be easier to understand.

This feature is unlikely to be used much in practice because it requires the
application to have two versions of the code that processes the results.
There would have to be a clearly demonstrable performance improvement to
make it worth writing and maintaining the code to utilize this feature.
Given that the implementation must copy the data regardless of the storage
order, the performance gained from matching the internal storage order is
unlikely to be large, particularly for small numbers of values.  Combined
with the fact that most applications will either query large numbers of
entities infrequently or small numbers of entities frequently, there is
unlikely to ever be a justification for coding the application to allow the
implementation to determine the storage order.

Further, it just isn't necessary for the implementation to pass back its
default storage order from every such call.  If the application wants to
utilize this feature, it can call getDfltStorage once at startup and pass
the resulting value into any function that it would have passed in
iBase_UNDETERMINED.

This change makes the API a little more convenient for the applications that
specify a particular storage order.  Rather than needing to declare a
temporary integer so the storage order can be passed by value, the
application may specify the storage order literally as one of its arguments.
 For example:
  iMesh_getVtxArrCoords( instance, handles, num_handles, iBase_INTERLEAVED,
                         &coord_arr, &junk1, &junk2, &err );
rather than:
  int order = iBase_INTERLEAVED;
  iMesh_getVtxArrCoords( instance, handles, num_handles, &order
                         &coord_arr, &junk1, &junk2, &err );

This change would also make the API easier to understand.  I think that if I
saw a pass-by-value storage order argument and two possible values for
iBase_StorageOrder, the behavior would be clear without the need for any
additional documentation.  I don't think the same is true with the current API.

- jason