On Thu, Dec 19, 2013 at 11:59 AM, Christopher Sean Morrison <[email protected]> wrote: > Below are several thoughts on our API evolution. Not a rant, just words of > concern and motivation. > >> -extern const struct db5_attr_ctype db5_attr_std[]; >> +RT_EXPORT extern const struct db5_attr_ctype db5_attr_std[]; > > I'm slowly catching up but am quite behind on my usual commit reviews, but > this recent unveil > is a bit concerning.. a global array being added to librt?
That whole API setup was primarily to have something concrete to discuss when it comes to what we want to implement and how - that's rather unclear at the moment. > I have seen all of the attr work recently (Tom et al.), but haven't gotten > into the details. We're kind of waiting until you can :-). > I don't think we want to be introducing any new globals, especially not > crash-prone arrays to public API. > Moreover, the library should be stateless or parallelism is ruined and > arrays are implicit state. There are other ways... :) The intent of that array is to be a strictly read-only list of standard BRL-CAD attributes - it is not something that would be updated at run-time. I was figuring read-only was safe, but of course I could be wrong... Also my assumption was that the core notion of a "standard" attribute in this context meant "definition and characteristics not alterable by users", but that may not be a universal assumption. > I was also under the assumption that we'd be handling "standard" attributes > via namespacing > (i.e., a 'cad:' naming prefix convention), but I'll hold those thoughts until > the current design > can be reviewed appropriately. I may be simply not understanding properly what the approach will be, but whether the "standard" attributes are prefixed or not (I'm assuming this is a prefix on the attributes themselves, and not referring to using a C++ namespace?) the question of where information about them is stored needs to be addressed in some fashion. I'm assuming the "standard" attribute array is intended to be something that is unalterable as far as applications are concerned, and thus needs to be "compiled in" in some fashion. Perhaps I'm just not properly understanding earlier discussions... > There's nothing that precludes them from being stored separate, but it may > be unnecessary complexity. I don't follow - by "stored separate" do you mean in a text file somewhere that is loaded at run time? > Something for all to remember is our goal to have 100% complete API > documentation. That means every > new line that goes into a file in the include/ directory (every #define > value, macro, function decl, variable > decl, ...) is required to have documentation. We should be cautious, > resistant even, to adding new > complexity to the public APIs. And if we can implement something by adding > fewer things that need > /** */ documentation, we should. Less is definitely more. My expectation was that most of the attr API I had roughed out would probably go away fairly quickly once we've properly defined what approach we want - it's not even clear to me at this point what features we are wanting to provided in an attribute API. I was trying to have something concrete on which to base the discussions, but perhaps we aren't ready for that yet. CY ------------------------------------------------------------------------------ Rapidly troubleshoot problems before they affect your business. Most IT organizations don't have a clear picture of how application performance affects their revenue. With AppDynamics, you get 100% visibility into your Java,.NET, & PHP application. Start your 15-day FREE TRIAL of AppDynamics Pro! http://pubads.g.doubleclick.net/gampad/clk?id=84349831&iu=/4140/ostg.clktrk _______________________________________________ BRL-CAD Developer mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/brlcad-devel
