>>>> 2009-12-08 13:39 UTC+0100 Viktor Szakats (harbour.01 syenar.hu) >>>> * contrib/hbcairo/core.c >>>> + Enabled HB_USE_ITEM mode which doesn't use Harbour internals. >>> Viktor, I do not think this is a good commit before questions about GC API >>> are finally solved. >> As per Przemek's last commit, both versions work now equally well, both >> versions are equal in length, but non-internal is much easier to understand, > > The "non-internal" version is more *difficult* to understand. > To understand it you must know how collectible pointers are stored in items, > you must know that does "locked item" means. Do you know why hb_gcUnlock() is > used, what will go wrong if it will not be used? Why GC marking will be > redundant without hb_gcUnlock()?
It's still the documented way, and documented APIs look much more familiar to 99.99% of developers. Anyhow both methods require quite advanced knowledge, but the internal version is more cryptic to me, since I've very rarely seen or heard about those calls. I for one would be happy to grasp _one_ example and apply it to other projects. >> Maybe I'm missing something but I fail to see why internal version should be >> used at this point. Does it give much more performance? > > This is not a speed question here. For me usage of GC reference counter is > more clear than usage of extra item to force keeping GC block unreleased. In > "non-internal" version we have references: > iterator -> item -> path > otherwise: > iterator -> path > > This extra item is not useful by itself. The whole C code operates on path, > these is no interfacing to .prg level here. We do not need an item here, we > need path only. In this case this extra item is just a workaround to keep > path reference counter increased instead of direct hb_gcRefInc() call. I don't mind if a PHB_ITEM container is used if it makes sense, or makes coding simpler or documented. I trust Przemek's judgment that these low-level functions are marked as internals for good reason. After all the last thing we want to do is help users creating risky or easily breakable code with hard-to-oversee side effects. (there are quite many options to write bad code anyway). Of course it's possible that these internal APIs can be tamed, and made available as public ones, I have nothing against it, but at this moment this is not the case. This means in this case, that it's an optimization to drop PHB_ITEM with the help of Harbour internals. > I want to see the second version (without extra item) working by default in > the final code, but I want to leave HB_USE_ITEM define, to make users have a > sample of various ways to cross-reference GC blocks. They can see both of > versions, compare it and understand how things work. I'd like to leave only one option and it's a strong opinion. I see no point at all to give user options for such a small and low-level details, which only 2-3 ppl understand in the whole Harbour community. I've cleaned several dozens of such options in the past for good. It's our/developers' job to chose best method and use that consistently in code. Remember that contribs are the best examples for 3rd party developers to follow, and presenting them options is rather only good to confuse them and mix them, and make mistakes. These techniques are eventually copied to other projects, so we should be careful what to include and it should be the _best_ _documented_ way of doing things. IOW, for documentation of _possible alternate techniques_ and coding options, the live SVN codebase is not the best place. Such information is useful only for expert users and should be added to /doc, instead of final code. But: Even such docs shouldn't refer to undocumented internals. Brgds, Viktor _______________________________________________ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
