create/destroy name change proposal

[Carl Ollivier-Gooch]

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

-- 
------------------------------------------------------------------------
Dr. Carl Ollivier-Gooch, P.Eng.                   Voice: +1-604-822-1854
Associate Professor                                 Fax: +1-604-822-2403
Department of Mechanical Engineering             email: cfog at mech.ubc.ca
University of British Columbia              http://www.mech.ubc.ca/~cfog
Vancouver, BC  V6T 1Z4                  http://tetra.mech.ubc.ca/ANSLab/
------------------------------------------------------------------------