create/destroy name change proposal

[Xiaolin Li]

This proposal looks fine with FronTier.

On Wed, 2010-05-05 at 10:16 -0400, Carl Ollivier-Gooch wrote:
> I redirected this to the interface list, to help signal-to-noise ratio.
> 
> On 10-04-29 09:30 PM, Mark Miller wrote:
> > Author(s):
> > ----------
> > Mark C. Miller
> >
> > Proposal:
> > ---------
> > Change the name(s) of a few iMesh functions to make the API a little
> > more consistently named. For convenience, I list below the names of many
> > fuctions that add/remove or create/destroy things.
> >
> >          Add/Remove methods
> >          ------------------
> >          iMesh_addEntToSet/iMesh_rmvEntFromSet
> >          iMesh_addEntArrToSet/iMesh_rmvEntArrFromSet
> >          iMesh_addEntSet/iMesh_rmvEntSet
> >          iMesh_addPrntChld/iMesh_rmvPrntChld
> >          no-add-method/iMesh_rmvEntSetTag
> >          no-add-method/iMesh_rmvArrTag
> >          no-add-method/iMesh_rmvTag
> >
> >          Create/Destroy methods (sort of)
> >          --------------------------------
> >          iMesh_newMesh/iMesh_dtor
> >          iMesh_createEntSet/iMesh_destroyEntSet
> >          iMesh_createVtxArr/iMesh_deleteEntArr
> >          iMesh_createEntArr/iMesh_deleteEntArr
> >          iMesh_createTag/iMesh_destroyTag
> >          iMesh_createVtx/iMesh_deleteEnt
> >          iMesh_createEnt/iMesh_deleteEnt
> >
> > So, I propose to rename the following functions...
> >
> >          iMesh_newMesh -->  iMesh_create
> >          iMesh_dtor -->  iMesh_destroy
> >
> >          iMesh_deleteEnt -->  iMesh_destroyEnt
> >          iMesh_deleteEntArr -->  iMesh_destroyEntArr
> >
> > Rational:
> > ---------
> > For the most part, we have an 'add' operation that adds an existing
> > thing to another existing thing and a corresponding 'remove' operation
> > that undoes whatever the add did.
> 
> I have no complaints about rationalizing the names.  These are the way 
> they are for no particularly good reason.  The _dtor, for instance, is a 
> carryover from the name SIDL pushed on us....
> 
> > Related concern #1:
> > ------------------
> > What says the specification regarding what is supposed to happen to
> > storage associated with the things being removed or destroy? I could not
> > find anything that specifically enumerates what, if anything, an
> > implementation is required to do with removing or destroying things with
> > the storage associated with those things. If we give implementations
> > flexibility what to do with storage, I could envision implementations
> > where a remove operation just indicates internally that an item should
> > be ignored but otherwise does nothing to free up any storage that might
> > be associated with the item having been previously added. Likewise for
> > 'destroy' operations. Worse, I could storage that is 'lost' to removed
> > or destroy'd things being kept around presisting across save/load which
> > would be even worse. So, I think the specification should speak to the
> > issue of an implementation's responsibility regarding storage associated
> > with things being removed/destroyed.
> 
> Can of worms warning! :-)
> 
> GRUMMP is one of the implementations that marks stuff as removed without 
> freeing up storage.  Rationale: entities are created internally in 
> blocks rather than one by one.  Removing an entity in the middle of a 
> block with compression of the remaining data is O(n) for every deletion, 
> which is bad.  Actually, it's worse, because that changes all of your 
> connectivity data (whether you use integers or pointers).  And it's even 
> worse than that, because the way GRUMMP stores sets and entity handle 
> tags is by using pointers to entities.  So if I compress the data 
> structures, all of that stuff has to be updated.
> 
> As a result, the compression is done in batch and only occasionally. 
> This is why we have this obscure function about handle validity: to give 
> implementations notice that it's okay to rearrange the database without 
> messing up handles that the application may be holding on to.  When the 
> database is compressed, blocks of memory with no entities in them are 
> freed, but the remaining blocks won't be 100% full (except by remarkable 
> coincidence).
> 
> GRUMMP -does- compress the database before writing (actually, it also 
> reorders at this point, too).  So there's no carryover of 
> non-garbage-collected memory to the next run.
> 
> > Related concern #2:
> > -------------------
> > In three of the remove methods for tags, above, we have no corresponding
> > 'add' method. Instead, I think a call to iMesh_set<Whatever>Data has the
> > effect of both 'adding' the tag and setting the data value. That just
> > seems a little inconsistent too.
> 
> Yes, but.  The "but" is that if you can add a tag without setting it, 
> now you have to have some (implementation dependent, at least for 
> handles) automatic value to assign.  This is true in a different form 
> even if we mandate that iMesh_get<>Data for an added-but-unset tag 
> returns an error: how does the implementation know that the value hasn't 
> been set yet?
> 
> Overall, I think the inconsistency is worth it here: it eliminates a 
> call in common usage (the only correct usage that I can see) and makes 
> implementation easier.
> 
> Carl
>