[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: <kfogel_at_collab.net>
Date: 2005-10-04 21:07:50 CEST

"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

> 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.

> 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?).

> 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.

> 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().

Thoughts? Any objections to these assertions and solutions?

Thanks for pointing out these problems,

To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Oct 4 22:17:55 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.