You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Max Bowsher <ma...@ukf.net> on 2005/10/04 13:55:43 UTC
The meaning of double-underscore symbols
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.
The double-underscore symbols which do not meet the strictest definition
are:
svn_error__locate: used almost everywhere
svn_sort__hash: used by libsvn_client, mod_dav_svn, and svn
svn_{fs,ra}_foo__init: linked into the loader libs
svn_txdelta__apply_instructions, svn_txdelta__compose_windows: used by the
fs backends
If anyone knows of an official definition of what svn_foo__bar means, please
tell me, otherwise, opinions and thoughts welcome, so we can craft an
official definition.
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Max Bowsher <ma...@ukf.net>.
kfogel@collab.net wrote:
> "Max Bowsher" <ma...@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
here.
>> 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
use.
>> 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.
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 04 Oct 2005 14:49:28 -0500, kfogel@collab.net <kf...@collab.net> wrote:
> Can you say a scenario you have in mind, where having the symbols be
> in the object code, even if not the source code, would be a problem?
> I feel like I may be being insufficiently imaginative here...
I believe he means that if a client of the subversion libraries is
built with a version that uses svn_error__locate() (even if via our
macros), they will then require that symbol to be present in the
version of the subversion libraries they use at runtime. So even
though the symbol never shows up in the client source code, there's
still a hard dependency on it encoded into the client object code, so
it can only be changed or removed when we break compatibility (i.e. a
major version rev).
-garrett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Max Bowsher <ma...@ukf.net>.
kfogel@collab.net wrote:
> Philip Martin <ph...@codematters.co.uk> writes:
>>> "Max Bowsher" <ma...@ukf.net> writes:
>>>> 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.
>>
>> Although macros hide the double underscore name at the source code
>> level, the compiled object code will still have a dependency on the
>> svn_error__locate name. Thus we have to treat svn_error__locate like
>> any other public symbol, despite the use of double underscore.
>
> It depends on what "treat ... like" means, exactly.
>
> Internally, Subversion can guarantee (to itself) that it will only use
> svn_error__locate() for these macros. Thus, anyone using the macros
> together with the correct set of full Subversion libraries -- which is
> how we say Subversion works -- will not run into trouble. Were we to
> change the definition of svn_error__locate(), we'd change the macros
> at the same time.
>
> Can you say a scenario you have in mind, where having the symbols be
> in the object code, even if not the source code, would be a problem?
> I feel like I may be being insufficiently imaginative here...
ABI compatibility.
We have promised that stuff compiled against 1.2 will run with 1.3 libs,
etc.
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Branko Čibej <br...@xbc.nu>.
kfogel@collab.net wrote:
>Philip Martin <ph...@codematters.co.uk> writes:
>
>
>>>"Max Bowsher" <ma...@ukf.net> writes:
>>>
>>>
>>>>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.
>>>
>>>
>>Although macros hide the double underscore name at the source code
>>level, the compiled object code will still have a dependency on the
>>svn_error__locate name. Thus we have to treat svn_error__locate like
>>any other public symbol, despite the use of double underscore.
>>
>>
>
>It depends on what "treat ... like" means, exactly.
>
>Internally, Subversion can guarantee (to itself) that it will only use
>svn_error__locate() for these macros. Thus, anyone using the macros
>together with the correct set of full Subversion libraries -- which is
>how we say Subversion works -- will not run into trouble. Were we to
>change the definition of svn_error__locate(), we'd change the macros
>at the same time.
>
>Can you say a scenario you have in mind, where having the symbols be
>in the object code, even if not the source code, would be a problem?
>I feel like I may be being insufficiently imaginative here...
>
>
Well, as matter of fact, I'd like to fix the build so the
double-underscore symbols are never exported from the shared libraries.
Current exceptions would remain such, but in general, it's either public
(and exported) or not (and therefore not exported).
I'm fairly sure that there are library users out there that are happily
using those private symbols, and will scream when we change the
semantics/signature/whatever.
-- Brane
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Philip Martin <ph...@codematters.co.uk>.
Branko Čibej <br...@xbc.nu> writes:
> Well, in the particualr case of svn_error__locate, that's only used in
> maintainer mode. I don't think anyone has any business using
> maintainer-mode libraries in production.
I think you are mistaken. Code that includes svn_error.h and uses
svn_error_create, or one of the other wrapper macros, will generate
object code that refers to svn_error__locate. The Subversion
libraries must continue to provide the symbol, and while we do have
some freedom to change it's implementation it must never require
anything other that the two current parameters.
--
Philip Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Branko Čibej <br...@xbc.nu>.
Philip Martin wrote:
>kfogel@collab.net writes:
>
>
>
>>Can you say a scenario you have in mind, where having the symbols be
>>in the object code, even if not the source code, would be a problem?
>>I feel like I may be being insufficiently imaginative here...
>>
>>
>
>It's no different from any other public symbol.
>
>If some third-party code uses SVN_ERR and gets built against
>Subversion 1.2 the object code will refer to svn_err__locate. If we
>change svn_err__locate in 1.4 and make it incompatible with 1.2 then
>the object code will not work with the 1.4 libraries and we will have
>broken the ABI guarantees. Having the SVN_ERR macro remain source
>compatible doesn't get round this problem.
>
>
Well, in the particualr case of svn_error__locate, that's only used in
maintainer mode. I don't think anyone has any business using
maintainer-mode libraries in production.
-- Brane
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Philip Martin <ph...@codematters.co.uk>.
kfogel@collab.net writes:
> Can you say a scenario you have in mind, where having the symbols be
> in the object code, even if not the source code, would be a problem?
> I feel like I may be being insufficiently imaginative here...
It's no different from any other public symbol.
If some third-party code uses SVN_ERR and gets built against
Subversion 1.2 the object code will refer to svn_err__locate. If we
change svn_err__locate in 1.4 and make it incompatible with 1.2 then
the object code will not work with the 1.4 libraries and we will have
broken the ABI guarantees. Having the SVN_ERR macro remain source
compatible doesn't get round this problem.
--
Philip Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by kf...@collab.net.
Philip Martin <ph...@codematters.co.uk> writes:
> > "Max Bowsher" <ma...@ukf.net> writes:
> >> 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.
>
> Although macros hide the double underscore name at the source code
> level, the compiled object code will still have a dependency on the
> svn_error__locate name. Thus we have to treat svn_error__locate like
> any other public symbol, despite the use of double underscore.
It depends on what "treat ... like" means, exactly.
Internally, Subversion can guarantee (to itself) that it will only use
svn_error__locate() for these macros. Thus, anyone using the macros
together with the correct set of full Subversion libraries -- which is
how we say Subversion works -- will not run into trouble. Were we to
change the definition of svn_error__locate(), we'd change the macros
at the same time.
Can you say a scenario you have in mind, where having the symbols be
in the object code, even if not the source code, would be a problem?
I feel like I may be being insufficiently imaginative here...
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Philip Martin <ph...@codematters.co.uk>.
kfogel@collab.net writes:
> "Max Bowsher" <ma...@ukf.net> writes:
>> 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.
Although macros hide the double underscore name at the source code
level, the compiled object code will still have a dependency on the
svn_error__locate name. Thus we have to treat svn_error__locate like
any other public symbol, despite the use of double underscore.
--
Philip Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by "Peter N. Lundblad" <pe...@famlundblad.se>.
On Tue, 4 Oct 2005 kfogel@collab.net wrote:
> "Max Bowsher" <ma...@ukf.net> writes:
> > 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.
>
They are internal because they are part of the internal interface between
libsvn_ra and libsvn_ra_foo (or fs) I don't consider libsvn_ra_foo as a
public library (except for the deprecated interface). We can change the
vtable at will. That they are libraries is just so they can be dynamically
linked if so desired. At least this was my thinking when I did the svn_ra
API rework for 1.2.
Regards,
//Peter
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by kf...@collab.net.
"Max Bowsher" <ma...@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.
> 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,
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Max Bowsher <ma...@ukf.net>.
C. Michael Pilato wrote:
> "Max Bowsher" <ma...@ukf.net> writes:
>
>> It is unclear exactly what is allowed to make use of these symbols -
>> only the library containing that symbol, or any code within the
>> subversion project.
>
> If only the library containing the symbol could access it, the symbol
> would be best defined in a library-specific header file (fs.h, not
> svn_fs.h; wc.h, not svn_wc.h). If any code within the subversion
> project could use it, I would think it would be in /include (though
> ideally with big ol' warnings about how it was an internal-use-only
> symbol).
Ah! I see, there are two kinds of double-underscore symbol. That makes
things clearer.
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by "C. Michael Pilato" <cm...@collab.net>.
"Max Bowsher" <ma...@ukf.net> writes:
> It is unclear exactly what is allowed to make use of these symbols -
> only the library containing that symbol, or any code within the
> subversion project.
If only the library containing the symbol could access it, the symbol
would be best defined in a library-specific header file (fs.h, not
svn_fs.h; wc.h, not svn_wc.h). If any code within the subversion
project could use it, I would think it would be in /include (though
ideally with big ol' warnings about how it was an internal-use-only
symbol).
--
C. Michael Pilato <cm...@collab.net>
CollabNet <> www.collab.net <> Distributed Development On Demand
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Max Bowsher <ma...@ukf.net>.
Joshua Varner wrote:
> On 10/4/05, Max Bowsher <ma...@ukf.net> wrote:
>> 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.
>>
>>
>> The double-underscore symbols which do not meet the strictest definition
>> are:
>>
>> svn_error__locate: used almost everywhere
>> svn_sort__hash: used by libsvn_client, mod_dav_svn, and svn
>> svn_{fs,ra}_foo__init: linked into the loader libs
>> svn_txdelta__apply_instructions, svn_txdelta__compose_windows: used by
>> the
>> fs backends
>>
>>
>> If anyone knows of an official definition of what svn_foo__bar means,
>> please tell me, otherwise, opinions and thoughts welcome, so we can craft
>> an official definition.
>>
>>
> Are you saying this section from
> http://subversion.tigris.org/hacking.html#other-conventions
> is incomplete or that is just hard to find? I believe this implies b.
>
> QUOTE
> Signify internal variables by two underscores after the prefix. That
> is, when a symbol must (for technical reasons) reside in the global
> namespace despite not being part of a published interface, then use
> two underscores following the module prefix. For example:
>
> svn_fs_get_rev_prop () /* Part of published API. */
> svn_fs__parse_props () /* For internal use only. */
> END QUOTE
It is unclear exactly what is allowed to make use of these symbols - only
the library containing that symbol, or any code within the subversion
project.
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Joshua Varner <jl...@gmail.com>.
On 10/4/05, Max Bowsher <ma...@ukf.net> wrote:
> 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.
>
>
> The double-underscore symbols which do not meet the strictest definition
> are:
>
> svn_error__locate: used almost everywhere
> svn_sort__hash: used by libsvn_client, mod_dav_svn, and svn
> svn_{fs,ra}_foo__init: linked into the loader libs
> svn_txdelta__apply_instructions, svn_txdelta__compose_windows: used by the
> fs backends
>
>
> If anyone knows of an official definition of what svn_foo__bar means, please
> tell me, otherwise, opinions and thoughts welcome, so we can craft an
> official definition.
>
>
Are you saying this section from
http://subversion.tigris.org/hacking.html#other-conventions
is incomplete or that is just hard to find? I believe this implies b.
QUOTE
Signify internal variables by two underscores after the prefix. That
is, when a symbol must (for technical reasons) reside in the global
namespace despite not being part of a published interface, then use
two underscores following the module prefix. For example:
svn_fs_get_rev_prop () /* Part of published API. */
svn_fs__parse_props () /* For internal use only. */
END QUOTE
Josh
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: The meaning of double-underscore symbols
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 10/4/05, Max Bowsher <ma...@ukf.net> wrote:
> If anyone knows of an official definition of what svn_foo__bar means, please
> tell me, otherwise, opinions and thoughts welcome, so we can craft an
> official definition.
I was under the impression that the double underscore was for symbols
that for some technical reason need to be globally visible, but that
we do not want code outside the Subversion codebase depending on.
-garrett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org