jiigen666/libtorrent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

deprecated a bunch of query functions on torrent_handle in favor of using status() to get as much information as possible in fewer calls, and saving time on synchronizing with the main thread

Browse Source
This commit is contained in:
Arvid Norberg
2010-10-30 17:23:30 +00:00
parent 415cd7fc4f
commit a76570b563
14 changed files with 171 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/manual.rst
View File

@@ -139,7 +139,6 @@ The ``session`` class has the following synopsis::
void pause();
void resume();
bool is_paused() const;
session_proxy abort();
@@ -1883,6 +1882,16 @@ torrent_handle
You will usually have to store your torrent handles somewhere, since it's the
object through which you retrieve information about the torrent and aborts the torrent.
.. warning::
Any member function that returns a value or fills in a value has to
be made synchronously. This means it has to wait for the main thread
to complete the query before it can return. This might potentially be
expensive if done from within a GUI thread that needs to stay responsive.
Try to avoid quering for information you don't need, and try to do it
in as few calls as possible. You can get most of the interesting information
about a torrent from the ``torrent_handle::status()`` call.
Its declaration looks like this::
struct torrent_handle
@@ -1958,7 +1967,6 @@ Its declaration looks like this::
enum pause_flags_t { graceful_pause = 1 };
void pause(int flags = 0) const;
void resume() const;
bool is_paused() const;
bool is_seed() const;
void force_recheck() const;
void clear_error() const;
@@ -1984,10 +1992,8 @@ Its declaration looks like this::
void prioritize_files(std::vector<int> const& files) const;
std::vector<int> file_priorities() const;
bool is_auto_managed() const;
void auto_managed(bool m) const;
bool has_metadata() const;
bool set_metadata(char const* buf, int size) const;
boost::filesystem::path save_path() const;
@@ -2357,13 +2363,12 @@ limit.
download, respectively.
set_sequential_download() is_sequential_download()
--------------------------------------------------
set_sequential_download()
-------------------------
::
void set_sequential_download(bool sd);
bool is_sequential_download() const;
``set_sequential_download()`` enables or disables *sequential download*. When enabled, the piece
picker will pick pieces in sequence instead of rarest first.
@@ -2371,10 +2376,6 @@ picker will pick pieces in sequence instead of rarest first.
Enabling sequential download will affect the piece distribution negatively in the swarm. It should be
used sparingly.
``is_sequential_download()`` returns true if this torrent is downloading in sequence, and false
otherwise.
get_peer_download_limit() get_peer_upload_limit() set_peer_upload_limit() set_peer_download_limit()
---------------------------------------------------------------------------------------------------
@@ -2389,21 +2390,22 @@ Works like ``get_upload_limit``, ``get_download_limit``, ``set_upload_limit`` an
``set_download_limit`` respectively, but controls individual peer instead of the
whole torrent.
pause() resume() is_paused()
----------------------------
pause() resume()
----------------
::
enum pause_flags_t { graceful_pause = 1 };
void pause(int flags) const;
void resume() const;
bool is_paused() const;
``pause()``, and ``resume()`` will disconnect all peers and reconnect all peers respectively.
When a torrent is paused, it will however remember all share ratios to all peers and remember
all potential (not connected) peers. You can use ``is_paused()`` to determine if a torrent
is currently paused. Torrents may be paused automatically if there is a file error (e.g. disk full)
or something similar. See file_error_alert_.
all potential (not connected) peers. Torrents may be paused automatically if there is a file
error (e.g. disk full) or something similar. See file_error_alert_.
To know if a torrent is paused or not, call ``torrent_handle::status()`` and inspect
``torrent_status::paused``.
The ``flags`` argument to pause can be set to ``torrent_handle::graceful_pause`` which will
delay the disconnect of peers that we're still downloading outstanding requests from. The torrent
@@ -2415,11 +2417,6 @@ torrents that are auto-managed may be automatically resumed again. It does not m
pause an auto-managed torrent without making it not automanaged first. Torrents are auto-managed
by default when added to the session. For more information, see queuing_.
``is_paused()`` only returns true if the torrent itself is paused. If the torrent
is not running because the session is paused, this still returns false. To know if a
torrent is active or not, you need to inspect both ``torrent_handle::is_paused()``
and ``session::is_paused()``.
flush_cache()
-------------
@@ -2509,32 +2506,23 @@ is_seed()
Returns true if the torrent is in seed mode (i.e. if it has finished downloading).
is_auto_managed() auto_managed()
--------------------------------
auto_managed()
--------------
::
bool is_auto_managed() const;
void auto_managed(bool m) const;
``is_auto_managed()`` returns true if this torrent is currently *auto managed*.
``auto_managed()`` changes whether the torrent is auto managed or not. For more info,
see queuing_.
has_metadata() set_metadata()
-----------------------------
set_metadata()
--------------
::
bool has_metadata() const;
bool set_metadata(char const* buf, int size) const;
``has_metadata`` returns true if this torrent has metadata (either it was started from a
.torrent file or the metadata has been downloaded). The only scenario where this can return
false is when the torrent was started torrent-less (i.e. with just an info-hash and tracker
ip). Note that if the torrent doesn't have metadata, the member `get_torrent_info()`_ will
throw.
``set_metadata`` expects the *info* section of metadata. i.e. The buffer passed in will be
hashed and verified against the info-hash. If it fails, a ``metadata_failed_alert`` will be
generated. If it passes, a ``metadata_received_alert`` is generated. The function returns
@@ -2784,8 +2772,9 @@ Example code to pause and save resume data for all torrents and wait for the ale
i != handles.end(); ++i)
{
torrent_handle& h = *i;
if (!h.has_metadata()) continue;
if (!h.is_valid()) continue;
torrent_status s = h.status();
if (!s.has_metadata) continue;
h.save_resume_data();
++num_resume_data;
@@ -2991,6 +2980,10 @@ It contains the following fields::
state_t state;
bool paused;
bool auto_managed;
bool sequential_download;
bool seeding;
bool finished;
float progress;
int progress_ppm;
std::string error;
@@ -3126,7 +3119,29 @@ The torrent's current task is in the ``state`` member, it will be one of the fol
When downloading, the progress is ``total_wanted_done`` / ``total_wanted``. This takes
into account files whose priority have been set to 0. They are not considered.
``paused`` is set to true if the torrent is paused and false otherwise.
``paused`` is set to true if the torrent is paused and false otherwise. It's only true
if the torrent itself is paused. If the torrent is not running because the session is
paused, this is still false. To know if a torrent is active or not, you need to inspect
both ``torrent_status::paused`` and ``session::is_paused()``.
``auto_managed`` is set to true if the torrent is auto managed, i.e. libtorrent is
responsible for determining whether it should be started or queued. For more info
see queuing_
``sequential_download`` is true when the torrent is in sequential download mode. In
this mode pieces are downloaded in order rather than rarest first.
``is_seeding`` is true if all pieces have been downloaded.
``is_finished`` is true if all pieces that have a priority > 0 are downloaded. There is
only a distinction between finished and seeding if some pieces or files have been
set to priority 0, i.e. are not downloaded.
``has_metadata`` is true if this torrent has metadata (either it was started from a
.torrent file or the metadata has been downloaded). The only scenario where this can be
false is when the torrent was started torrent-less (i.e. with just an info-hash and tracker
ip, a magnet link for instance). Note that if the torrent doesn't have metadata, the member
`get_torrent_info()`_ will throw.
``error`` may be set to an error message describing why the torrent was paused, in
case it was paused by an error. If the torrent is not paused or if it's paused but
@@ -4546,7 +4561,7 @@ the default upload and download rate limits for peers, respectively. These
default to 0, which means unlimited. These settings affect the rate limits
set on new peer connections (not existing ones). The peer rate limits can
be changed individually later using
`set_peer_upload_limit() set_peer_download_limit()`_.
`get_peer_download_limit() get_peer_upload_limit() set_peer_upload_limit() set_peer_download_limit()`_.
if ``broadcast_lsd`` is set to true, the local peer discovery
(or Local Service Discovery) will not only use IP multicast, but also