create/destroy name change proposal

[Jason Kraftcheck]

Mark Miller wrote:
> Hi Mark,
> 
> I like yours and Carl's comments on this storage issue. However, I also
> think that together you have arrived at what the specification should
> say regarding storage associated with things being removed or deleted. I
> think both you and Carl are saying that the whether storage is freed up
> on remove/destroy operations is left to the implementation.
> 
> However, I also agree with your point that if iMesh_destroy (aka
> iMesh_dtor) did that, we'd be in a heap of trouble. So, the
> specification of iMesh_destroy should be that all memory associated with
> the iMesh instance be freed.
> 
> But, now that I think about it, that raises another question having to
> do with how the functions are named. I kinda sorta had in mind that any
> operation with 'destroy' in the name also freed memory while 'remove'
> did NOT say one way or the other.
> 

I agree with your first to paragraphs.  Not so much with the later one.  All
this function renaming is for consistency seems a little excessive for me.
While it would be nice to have consistent names, I just don't think it's
worth the API breakage..

But as long as we're discussing API changes and memory issues I'd like to
bring up a different issue that has bothered me for a while: the status
array passed back from iMesh_createEntArr.  I have two issues with this: a)
it is quite inconvenient and of dubious value and b) it is rather
inconsistent from an API POV.

What is the use case for this?  How many applications will truly check the
array to see which individual entity creations failed?  Is it worth having
every application remember to free this array as opposed to making that <1%
of applications that care about per-entity success/failure do their entity
creation one at a time?  Why not just have a flag selecting, for
implementations that do not allow duplicate entities, whether it should
return the handle for the existing entity or fail for duplicate entities.

As for b), I think that any function in the interface should free any arrays
allocated during the call before returning failure.  This is possible for
every function in the API except iMesh_createEntArr, which is required to
return an array when it fails.

- jason