extend documentation to cover start_when_ready (#2032)

extend documentation to cover start_when_ready and the trick to set all file priorities to 0 on a magnet link
This commit is contained in:
Arvid Norberg 2017-05-28 11:16:15 -04:00 committed by GitHub
parent 94701c24da
commit 7e653b9669
1 changed files with 30 additions and 1 deletions

View File

@ -186,6 +186,19 @@ The format of the magnet URI is:
**magnet:?xt=urn:btih:** *Base16 encoded info-hash* [ **&dn=** *name of download* ] [ **&tr=** *tracker URL* ]*
In order to download *just* the metadata (.torrent file) from a magnet link, set
file priorities to 0 in add_torrent_params::file_priorities. It's OK to set the
priority for more files than what is in the torrent. It may not be trivial to
know how many files a torrent has before the metadata has been downloaded.
Additional file priorities will be ignored. By setting a large number of files
to priority 0, chances are that they will all be set to 0 once the metadata is
received (and we know how many files there are).
In this case, when the metadata is received from the swarm, the torrent will
still be running, but it will disconnect the majority of peers (since connections
to peers that already have the metadata are redundant). It will keep seeding the
*metadata* only.
queuing
=======
@ -263,9 +276,25 @@ Once a torrent completes checking and moves into a diffferent state, the next in
line will be started for checking.
Any torrent added force-started or force-stopped (i.e. the auto managed flag is
_not_ set), will not be subject to this limit and they will all check
*not* set), will not be subject to this limit and they will all check
independently and in parallel.
Once a torrent completes the checking of its files, or fastresume data, it will
be put in the queue for downloading and potentially start downloading immediately.
In order to add a torrent and check its files without starting the download, it
can be added in ``stop_when_ready`` mode.
See add_torrent_params::flag_stop_when_ready. This flag will stop the torrent
once it is ready to start downloading.
This is conceptually the same as waiting for the ``torrent_checked_alert`` and
then call::
h.auto_managed(false);
h.pause();
With the important distinction that it entirely avoids the brief window where
the torrent is in downloading state.
downloading queue
-----------------