diff --git a/docs/index.rst b/docs/index.rst index bd490471a..237c7c485 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ * examples_ * overview_ * documentation_ +* `libtorrent 1.2`_ * contributing_ * building_ * troubleshooting_ @@ -67,6 +68,7 @@ libtorrent .. _examples: examples.html .. _overview: manual-ref.html .. _documentation: reference.html +.. _`libtorrent 1.2`: upgrade_to_1.2.html .. _troubleshooting: troubleshooting.html .. _`tuning`: tuning.html .. _screenshot: client_test.png diff --git a/docs/makefile b/docs/makefile index b60d416d0..b608bb9c8 100644 --- a/docs/makefile +++ b/docs/makefile @@ -50,6 +50,7 @@ TARGETS = index \ hacking \ streaming \ tutorial \ + upgrade_to_1.2 \ single-page-ref \ $(REFERENCE_TARGETS) diff --git a/docs/upgrade_to_1.2.rst b/docs/upgrade_to_1.2.rst new file mode 100644 index 000000000..731632997 --- /dev/null +++ b/docs/upgrade_to_1.2.rst @@ -0,0 +1,90 @@ +=========================== +Upgrading to libtorrent 1.2 +=========================== + +:Author: Arvid Norberg, arvid@libtorrent.org +:Version: 1.2.0 + +libtorrent version 1.2 comes with some significant updates in the API. +This document summarizes the changes affecting library users. + +C++98 no longer supported +------------------------- + +With libtorrent 1.2, C++98 is no longer supported, you need a compiler capable +of at least C++11 to build libtorrent. + +This also means libtorrent types now support move. + +forward declaring libtorrent types deprecated +--------------------------------------------- + +Clients are discouraged from forward declaring types from libtorrent. +Instead, include the header. + +A future release will intrduce ABI versioning using an inline namespace, which will break any forward declarations by clients. + +There is a new namespace alias, ``lt`` which is shorthand for ``libtorrent``. +In the future, ``libtorrent`` will be the alias and ``lt`` the namespace name. +With no forward declarations inside libtorrent's namespace though, there should not be any reason for clients to re-open the namespace. + +announce entry multi-home support +--------------------------------- + +The ``announce_entry`` type now captures status on individual endpoints, as opposed to treating every tracker behind the same name as a single tracker. +This means some properties has moved into the ``announce_endpoint`` structure, and an announce entry has 0 or more endpoints. + +alerts no longer cloneable +-------------------------- + +As part of the transition to a more efficient handling of alerts, 1.1 allocated them in a contiguous, heterogeneous, vector. +This means they are no longer heap allocated nor held by a smart pointer. +The ``clone()`` member on alerts was deprecated in 1.1 and removed in 1.2. +To pass alerts across threads, instead pull out the relevant information from the alerts and pass that across. + +boost replaced by std +--------------------- + +``boost::shared_ptr`` has been replaced by ``std::shared_ptr`` in the libtorrent API. +The same goes for ```` types, instead of ``boost::int64_t``, libtorrent now uses ``std::int64_t``. +Instead of ``boost::array``, ``std::array`` is used, and ``boost::function`` has been replaced by ``std::fuction``. + +strong typedefs +--------------- + +In order to strengthen type-safety, libtorrent now uses special types to represent certain indexes and ID types. +Any integer referring to a piece index, now has the type ``piece_index_t``, and indices to files in a torrent, use ``file_index_t``. +Similarly, time points and duration now use ``time_point`` and ``duration`` from the ```` standard library. + +The specific types have typedefs at ``lt::time_point`` and ``lt::duration``, and the clock used by libtorrent is ``lt::clock_type``.` + +span<> and string_view +---------------------- + +The interface has adopted ``string_view`` (from boost for now) and ``span<>`` (custom implementation for now). +This means some function calls that previously took ``char const*`` or ``std::string`` may now take an ``lt::string_view``. +Similarly, functions that previously would take a pointer and length pair will now take a ``span<>``. + +periphery utility functions no longer exported +---------------------------------------------- + +Historically, libtorrent has exported functions not essential to its core bittorrent functionality. +Such as filesystem functions like ``directory``, ``file`` classes and ``remove``, ``create_directory`` functions. +Path manipulation functions like ``combine_path``, ``extension``, ``split_path`` etc. +String manipulation functions like ``from_hex`` and ``to_hex``. +Time functions like ``time_now``. These functions are no longer available to clients, and some have been removed from the library. +Instead, it is recommended to use boost.filesystem or the experimental filesystem TS. + +plugins +------- + +libtorrent session plugins no longer have all callbacks called unconditionally. +The callback has to register which callbacks it's interested in receiving by returning a bitmask from ``std::uint32_t implemented_features()``. +The return value is documented in the plugin class. + +RSS functions removed +--------------------- + +The deprecated RSS functions have been removed from the library interface. + + diff --git a/include/libtorrent/kademlia/dht_state.hpp b/include/libtorrent/kademlia/dht_state.hpp index e882fcd1b..66639e8e0 100644 --- a/include/libtorrent/kademlia/dht_state.hpp +++ b/include/libtorrent/kademlia/dht_state.hpp @@ -53,9 +53,9 @@ namespace libtorrent { namespace dht { // This structure helps to store and load the state // of the ``dht_tracker``. // At this moment the library is only a dual stack - // implementation of the DHT. See BEP38_ + // implementation of the DHT. See `BEP 32`_ // - // .. _BEP32: http://bittorrent.org/beps/bep_0032.html + // .. _`BEP 32`: http://bittorrent.org/beps/bep_0032.html struct TORRENT_EXPORT dht_state { node_ids_t nids;