[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: The meaning of double-underscore symbols

From: Max Bowsher <maxb_at_ukf.net>
Date: 2005-10-05 00:41:29 CEST

kfogel@collab.net wrote:
> "Max Bowsher" <maxb@ukf.net> writes:
>> I don't believe we've ever defined *exactly* what the significance of
>> a double-underscore symbol name is.
>> Two of definitions I've heard of are:
>> (a) anything that should not be used by users, but can we used at will
>> internally by the Subversion libraries.
>> (b) symbols that should have visibility only to the library that they
>> are defined in, and should not be used *anywhere* outside that library.
> (b), and if that's not made clear enough in hacking.html, then we
> should fix the text. By "used", we mean "appear in the source code
> of", see below for why that distinction is important.
> Note that we sometime call svn__foo_* from C test code, but that's
> only because individual libraries don't have their own private test
> suites. As far as real code goes, only libsvn_foo should ever use
> svn__foo_*.
>> The double-underscore symbols which do not meet the strictest
>> definition are:
>> svn_error__locate: used almost everywhere
> Mmm, sort of.
> It's present in the expansions of some svn_err_* macros, but that's
> okay. Those macros are in the correct space, and whatever they want
> to do is fine, because the macro would always be changed along with
> the internal implementation on which it depends.

A seperate sub-thread has arisen discussing ABI compat, so I won't say more

>> svn_sort__hash: used by libsvn_client, mod_dav_svn, and svn
> This is a legacy problem, yes. It is a public function, appearing in
> a public header file, and it should be named accordingly. However,
> its doc string says:
> * @note Private. For use by Subversion's own code only. See issue #1644.
> *
> * @note This function and the @c svn_sort__item_t should go over to APR.
> Issue #1644 is closed now, and I don't feel any driving urge to move
> that function over to APR, so we should just rename it and leave the
> old name as an alias (perhaps using a macro?).

Nope, can't be a macro - ABI compat, again.

>> svn_{fs,ra}_foo__init: linked into the loader libs
> Yes, why aren't these public and single-underscore? If there's some
> circular dependency reason, it's okay, we can leave the current
> situation as it is (since the problem is unlikely to grow very much),
> but we should at least have a comment by those declarations explaining
> what
> is going on.

These are odd. They are very definitely NOT public, as their API is
partially mutable, but they are also explicitly intended for cross-library

>> svn_txdelta__apply_instructions, svn_txdelta__compose_windows: used by
>> the fs backends
> Badness. They should be public, single-underscore functions, just as
> recommended above for svn_sort__hash().

I agree on this.


To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Oct 5 00:42:18 2005

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.