[libtorrent] libtorrent ABI version namespace

[Arvid Norberg]

I posted a pull request that changes the (ABI) symbol names in libtorrent.
The purpose is to make it simpler to maintain backwards ABI compatibility
going forward.

The convention I've implemented in libtorrent is to make ABI breaking
changes every point release (x.y) but maintain ABI compatibility to
revisions within such release (x.y.z).

This means 1.2 will be ABI incompatible with current 1.1.x releases.

The change I'm considering does the following:

* renames the libtorrent namespace to "lt".
* adds another interior, inline, namespace with ABI version
* removes the previous (inferior) link-time ABI check (see
http://blog.libtorrent.org/2016/09/link-compatibility/ )
* introduces a namespace alias "libtorrent" to preserve backwards
compatibility

The PR is here: https://github.com/arvidn/libtorrent/pull/1879

The main benefit of this patch is that the ABI version is explicitly
encoded in the symbol names which improves error messages but also makes it
easier to preserve backwards compatibility going forward, by preserving
those symbols.

This change should not affect the API, and should only be noticeable by
clients in the following cases:

* forward declaring a libtorrent name would no longer work, as the
namespace would need to include the ABI version. In fact, opening the
namespace "libtorrent" for any reason would also not work, as that's an
alias now
* defining a namespace alias called "lt" would conflict with the new
namespace name of libtorrent.

Please let me know if anyone has any concerns or can think of problems that
would arise form merging this PR.

For more information on inline namespaces:


http://stackoverflow.com/questions/11016220/what-are-inline-namespaces-for

[sledgehammer999]

I am posting here because I don't to subscribe to a possibly long
discussions thread on github.

Post by Arvid Norberg
* forward declaring a libtorrent name would no longer work, as the

namespace would need to include the ABI version.

I am not good with terminology so I might have misunderstood you. Does that
mean that we cannot forward declare eg a public class in our client code
anymore? For example torrent_handle in header files?
qBittorrent currently does a lot of forward declaration of libtorrent
classes/structs in the headers. I have no real benchmark or figure but I
expect our compilation times to be quite longer in the future if we're
forced to not forward declare.

Post by Arvid Norberg
I posted a pull request that changes the (ABI) symbol names in libtorrent.
The purpose is to make it simpler to maintain backwards ABI compatibility
going forward.
The convention I've implemented in libtorrent is to make ABI breaking
changes every point release (x.y) but maintain ABI compatibility to
revisions within such release (x.y.z).
This means 1.2 will be ABI incompatible with current 1.1.x releases.
* renames the libtorrent namespace to "lt".
* adds another interior, inline, namespace with ABI version
* removes the previous (inferior) link-time ABI check (see
http://blog.libtorrent.org/2016/09/link-compatibility/ )
* introduces a namespace alias "libtorrent" to preserve backwards
compatibility
The PR is here: https://github.com/arvidn/libtorrent/pull/1879
The main benefit of this patch is that the ABI version is explicitly
encoded in the symbol names which improves error messages but also makes it
easier to preserve backwards compatibility going forward, by preserving
those symbols.
This change should not affect the API, and should only be noticeable by
* forward declaring a libtorrent name would no longer work, as the
namespace would need to include the ABI version. In fact, opening the
namespace "libtorrent" for any reason would also not work, as that's an
alias now
* defining a namespace alias called "lt" would conflict with the new
namespace name of libtorrent.
Please let me know if anyone has any concerns or can think of problems that
would arise form merging this PR.
http://stackoverflow.com/questions/11016220/what-are-inline-namespaces-for
--
Arvid Norberg
------------------------------------------------------------
------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Libtorrent-discuss mailing list
https://lists.sourceforge.net/lists/listinfo/libtorrent-discuss

[Arvid Norberg]

On Mon, Apr 3, 2017 at 7:19 PM, sledgehammer999 <

Post by Arvid Norberg

Post by Arvid Norberg
* forward declaring a libtorrent name would no longer work, as the

namespace would need to include the ABI version.
I am not good with terminology so I might have misunderstood you. Does that
mean that we cannot forward declare eg a public class in our client code
anymore?

Yes, with that patch, you wouldn't be able to.

Post by Arvid Norberg
For example torrent_handle in header files?
qBittorrent currently does a lot of forward declaration of libtorrent
classes/structs in the headers. I have no real benchmark or figure but I
expect our compilation times to be quite longer in the future if we're
forced to not forward declare.

This got me thinking. It's probably a better idea to transition into an abi
version namespace more gradually.
Something like:

1. discourage forward declaring of libtorrent types (just like std::)
2. instead of renaming the namespace, provide an alias for lt (for now)
3. as function's ABIs change, introduce the new version in an abi namespace

I think the problem with (3) is that changing ABI may still cause a
conflict in the API. I suspect:

namespace libtorrent {

struct add_torrent_params;

inline namespace v1 {
struct add_torrent_params;
}

}

The following would be ambiguous:

libtorrent::add_torrent_params;

[Arvid Norberg]

I conducted an experiment, and it definitely seems like the better (i.e.
more conservative) approach to introduce the abi namespace as ABI changes
are introduced. It appears symbols can coexist fine like that.

I put this test together:

https://github.com/arvidn/inline-namespace-abi-versioning

However, I cannot see any way to allow clients forward declaring names from
the libtorrent namespace. Any such forward declaration would necessarily
point to the old ABI version.
The approach I'm proposing would make it possible during a transition
period to still forward declare symbols, but as they get updated to newer
ABI versions, it would start falling apart.\

Post by Arvid Norberg
On Mon, Apr 3, 2017 at 7:19 PM, sledgehammer999 <

Post by Arvid Norberg

Post by Arvid Norberg
* forward declaring a libtorrent name would no longer work, as the

namespace would need to include the ABI version.
I am not good with terminology so I might have misunderstood you. Does that
mean that we cannot forward declare eg a public class in our client code
anymore?

Yes, with that patch, you wouldn't be able to.

Post by Arvid Norberg
For example torrent_handle in header files?
qBittorrent currently does a lot of forward declaration of libtorrent
classes/structs in the headers. I have no real benchmark or figure but I
expect our compilation times to be quite longer in the future if we're
forced to not forward declare.

This got me thinking. It's probably a better idea to transition into an
abi version namespace more gradually.
1. discourage forward declaring of libtorrent types (just like std::)
2. instead of renaming the namespace, provide an alias for lt (for now)
3. as function's ABIs change, introduce the new version in an abi namespace
I think the problem with (3) is that changing ABI may still cause a
namespace libtorrent {
struct add_torrent_params;
inline namespace v1 {
struct add_torrent_params;
}
}
libtorrent::add_torrent_params;
--
Arvid Norberg