create/destroy name change proposal

[Mark Miller]

On Thu, 2010-05-06 at 07:51, Jason Kraftcheck wrote:
> > 
> > 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..

Well, I think if we're concerned about barriers to adoption, we should
at least minimize those that we easily can. There are enough real
challenges and complexities in design and implementation of this API
that I think small things like consistency in naming is not excessive at
all by comparison.

> 
> 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? 

So, I don't think I've used this function in any of my code but I'll
comment anyway...

Also, what can the caller do with that information if it does find that
some creations failed? Call it a second time just with the entities that
failed on the first call? If the creation failed for lack of memory,
that isn't going to help. If the creation failed because the caller's
arguments are somehow NOT appropriate (e.g. defining a tet with 3 vertex
entities) do we really think they will 'get it right the second
attempt.'

Perhaps the spirit of that array was to serve the return value(s) that
would have been generated by calling createEnt many times in succession?

> 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.

Yeah, that sounds pretty unusual.

> 
> - jason
-- 
Mark C. Miller, Lawrence Livermore National Laboratory
================!!LLNL BUSINESS ONLY!!================
miller86 at llnl.gov      urgent: miller86 at pager.llnl.gov
T:8-6 (925)-423-5901     M/W/Th:7-12,2-7 (530)-753-851