premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

documentation fixes

This commit is contained in:
arvidn 2016-02-20 16:38:56 -05:00
parent 176d57ab8c
commit 5e4d6d139f
8 changed files with 80 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/contributing.html
View File

@ -75,7 +75,9 @@ as <tt class="docutils literal">explicit_cache</tt>).</p>
<dd><p class="first last">Finding typos or outdated sections in the documentation. Contributing documentation
based on your own experience and experimentation with the library or with BitTorrent
in general. Non-reference documentation is very much welcome as well, higher level
descriptions on how to configure libtorrent for various situations for instance.</p>
descriptions on how to configure libtorrent for various situations for instance.
The reference documentation for libtorrent is generated from the header files.
For updates, please submit a <a class="reference external" href="https://github.com/arvidn/libtorrent">pull request</a>.</p>
</dd>
</dl>
</li>
@ -83,7 +85,8 @@ descriptions on how to configure libtorrent for various situations for instance.
<dt>Code</dt>
<dd><p class="first">Contributing code for new features or bug-fixes is highly welcome. If you're interested
in adding a feature but not sure where to start, please contact the <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a> or
<tt class="docutils literal">#libtorrent</tt> &#64; <tt class="docutils literal">irc.freenode.net</tt>.</p>
<tt class="docutils literal">#libtorrent</tt> &#64; <tt class="docutils literal">irc.freenode.net</tt>. For proposed fixes or udpates, please
submit a <a class="reference external" href="https://github.com/arvidn/libtorrent">pull request</a>.</p>
<p class="last">New features might be better support for integrating with other services, new choking
algorithms, seeding policies, ports to new platforms etc.</p>
</dd>

7
docs/contributing.rst
View File

@ -34,11 +34,14 @@ enumerated on this page, please contact arvid@libtorrent.org or the `mailing lis
based on your own experience and experimentation with the library or with BitTorrent
in general. Non-reference documentation is very much welcome as well, higher level
descriptions on how to configure libtorrent for various situations for instance.
The reference documentation for libtorrent is generated from the header files.
For updates, please submit a `pull request`_.
3. Code
Contributing code for new features or bug-fixes is highly welcome. If you're interested
in adding a feature but not sure where to start, please contact the `mailing list`_ or
``#libtorrent`` @ ``irc.freenode.net``.
``#libtorrent`` @ ``irc.freenode.net``. For proposed fixes or udpates, please
submit a `pull request`_.
New features might be better support for integrating with other services, new choking
algorithms, seeding policies, ports to new platforms etc.
@ -49,5 +52,7 @@ For outstanding things to do, see the `todo list`_.
.. _hacking: hacking.html
.. _`pull request`: https://github.com/arvidn/libtorrent
.. _`todo list`: todo.html

16
docs/features.html
View File

@ -79,7 +79,7 @@ the library.</p>
</div>
<div class="section" id="features">
<h1>features</h1>
<p>libtorrent is under active development. It is an ongoing project. Its
<p>libtorrent is an ongoing project under active development. Its
current state supports and includes the following features:</p>
<div class="section" id="extensions">
<h2>extensions</h2>
@ -113,22 +113,22 @@ ratio rather than downloading the torrent.</li>
<div class="section" id="disk-management">
<h2>disk management</h2>
<ul class="simple">
<li>uses a separate disk I/O thread to not have the disk ever block on network or
client interaction. (see <a class="reference external" href="manualref.html#threads">threads</a>).</li>
<li>uses asynchronous disk I/O when available (overlapped I/O, kaio, and posix-aio)
to make optimal use of disk bandwidth capacity</li>
<li>supports verifying the SHA-1 hash of pieces in multiple threads, to take full
<li>can use multipled disk I/O threads to not have the disk block network or
client interaction.</li>
<li>supports verifying the SHA-1 hash of pieces in multiple threads, to take
advantage of multi core machines.</li>
<li>supports files &gt; 2 gigabytes.</li>
<li>fast resume support, a way to get rid of the costly piece check at the
<li>fast resume support, a way to avoid the costly piece check at the
start of a resumed torrent. Saves the storage state, piece_picker state
as well as all local peers in a separate fast-resume file.</li>
as well as all local peers in a fast-resume file.</li>
<li>has an adjustable read and write disk cache for improved disk throughput.</li>
<li>queues torrents for file check, instead of checking all of them in parallel.</li>
<li>does not have any requirements on the piece order in a torrent that it
resumes. This means it can resume a torrent downloaded by any client.</li>
<li>seed mode, where the files on disk are assumed to be complete, and each
piece's hash is verified the first time it is requested.</li>
<li>implements an ARC disk cache, tuned for performing well under bittorrent work
loads</li>
</ul>
</div>
<div class="section" id="network">

18
docs/features.rst
View File

@ -21,7 +21,7 @@ the library.
features
========
libtorrent is under active development. It is an ongoing project. Its
libtorrent is an ongoing project under active development. Its
current state supports and includes the following features:
extensions
@ -59,24 +59,22 @@ extensions
disk management
---------------
* uses a separate disk I/O thread to not have the disk ever block on network or
client interaction. (see threads_).
* uses asynchronous disk I/O when available (overlapped I/O, kaio, and posix-aio)
to make optimal use of disk bandwidth capacity
* supports verifying the SHA-1 hash of pieces in multiple threads, to take full
* can use multipled disk I/O threads to not have the disk block network or
client interaction.
* supports verifying the SHA-1 hash of pieces in multiple threads, to take
advantage of multi core machines.
* supports files > 2 gigabytes.
* fast resume support, a way to get rid of the costly piece check at the
* fast resume support, a way to avoid the costly piece check at the
start of a resumed torrent. Saves the storage state, piece_picker state
as well as all local peers in a separate fast-resume file.
as well as all local peers in a fast-resume file.
* has an adjustable read and write disk cache for improved disk throughput.
* queues torrents for file check, instead of checking all of them in parallel.
* does not have any requirements on the piece order in a torrent that it
resumes. This means it can resume a torrent downloaded by any client.
* seed mode, where the files on disk are assumed to be complete, and each
piece's hash is verified the first time it is requested.
.. _threads: manualref.html#threads
* implements an ARC disk cache, tuned for performing well under bittorrent work
loads
network
-------

20
docs/hacking.diagram
View File

@ -6,25 +6,25 @@
| "torrent_handle" +--------+ | |
+---------------------+ "weak" | +--------------+ |
| | | "m_connections[]"
| | +-------------+----+
| | | |
"m_picker" v v | v "peers we are connected to"
+----------------+ +----------++ +-------------------+
| "piece_picker" |<---+-+ "torrent" ++ +--+ "peer_connection" ++
+----------------+ | ++----------+| | ++------------------+|
"m_torrent_file" | +-----------+ | +-------------------+
| | +-------------+ +--+
| | | | |
"m_picker" v v | v v "peers we are connected to"
+----------------+ +----------++ +-------------------+
| "piece_picker" |<---+-+ "torrent" ++ +--+ "peer_connection" ++
+----------------+ | ++----------+| | ++------------------+|
"m_torrent_file" | +-----------+ | +-------------------+
+-------------------+ | |
| "torrent_info" |<---+ | "m_socket"
| "torrent_info" |<---+ | "m_socket"
+-------------------+ | | +----------------------------+
| +->| "socket_type (variant)" |
"m_peer_list" v | | "(TCP/uTP/SSL/socks5/...)" |
+--------------+ | +----------------------------+
| "peer_list" | |
| "peer_list" | |
+------------+-+ | "m_peer_info"
"list of all" | "m_peers[]" | "contains contact information"
"peers we" | | "for peers we're not necessarily"
"know of" | v "connected to"
| +----------------+
| +----------------+
+---->| "torrent_peer" ++
++---------------+|
+----------------+

13
docs/index.html
View File

@ -47,14 +47,13 @@
</table>
<div id="librarySidebar"><ul class="simple">
<li><a class="reference external" href="https://github.com/arvidn/libtorrent/releases">download</a></li>
<li><a class="reference external" href="https://sourceforge.net/projects/libtorrent/files/py-libtorrent/">download python binding</a></li>
<li><a class="reference external" href="features.html">features</a></li>
<li><a class="reference external" href="contributing.html">contributing</a></li>
<li><a class="reference external" href="building.html">building libtorrent</a></li>
<li><a class="reference external" href="examples.html">examples</a></li>
<li><a class="reference external" href="manual-ref.html">library overview</a></li>
<li><a class="reference external" href="manual-ref.html">overview</a></li>
<li><a class="reference external" href="reference.html">reference documentation</a></li>
<li><a class="reference external" href="troubleshooting.html">troubleshooting issues</a></li>
<li><a class="reference external" href="contributing.html">contributing</a></li>
<li><a class="reference external" href="building.html">building</a></li>
<li><a class="reference external" href="troubleshooting.html">troubleshooting</a></li>
<li><a class="reference external" href="tuning.html">tuning</a></li>
<li><a class="reference external" href="client_test.png">screenshot</a></li>
<li><a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a> (<a class="reference external" href="http://dir.gmane.org/gmane.network.bit-torrent.libtorrent">archive</a>)</li>
@ -125,8 +124,8 @@ list or posted to the <a class="reference external" href="https://github.com/arv
</div>
<div class="section" id="acknowledgements">
<h2>Acknowledgements</h2>
<p>Written by Arvid Norberg. Copyright © 2003-2015</p>
<p>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
<p>Written by Arvid Norberg. Copyright © 2003-2016</p>
<p>Contributions by Steven Siloti, Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>
<p>Thanks to <a class="reference external" href="http://www.cs.umu.se">Umeå University</a> for providing development and test hardware.</p>
<p>Project is hosted by <a class="reference external" href="https://www.github.com/arvidn/libtorrent">github</a>.</p>

21
docs/index.rst
View File

@ -6,14 +6,13 @@
<div id="librarySidebar">
* download_
* `download python binding`_
* features_
* contributing_
* `building libtorrent`_
* examples_
* `library overview`_
* overview_
* `reference documentation`_
* `troubleshooting issues`_
* contributing_
* building_
* troubleshooting_
* `tuning`_
* screenshot_
* `mailing list`_ (archive_)
@ -58,14 +57,13 @@ libtorrent
==========
.. _download: https://github.com/arvidn/libtorrent/releases
.. _`download python binding`: https://sourceforge.net/projects/libtorrent/files/py-libtorrent/
.. _features: features.html
.. _contributing: contributing.html
.. _`building libtorrent`: building.html
.. _building: building.html
.. _examples: examples.html
.. _`library overview`: manual-ref.html
.. _overview: manual-ref.html
.. _`reference documentation`: reference.html
.. _`troubleshooting issues`: troubleshooting.html
.. _troubleshooting: troubleshooting.html
.. _`tuning`: tuning.html
.. _screenshot: client_test.png
.. _`uTP`: utp.html
@ -104,7 +102,6 @@ The main goals of libtorrent are:
* to be memory efficient
* to be very easy to use
Donate
======
@ -147,9 +144,9 @@ list or posted to the `bug tracker`_.
Acknowledgements
================
Written by Arvid Norberg. Copyright |copy| 2003-2015
Written by Arvid Norberg. Copyright |copy| 2003-2016
Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson
Contributions by Steven Siloti, Magnus Jonsson, Daniel Wallin and Cory Nelson
Thanks to Reimond Retz for bugfixes, suggestions and testing

56
docs/todo.html
View File

@ -349,8 +349,8 @@ unchoking</h2><h4>../src/session_impl.cpp:4105</h4><pre style="background: #f6f6
if (pi &amp;&amp; pi-&gt;optimistically_unchoked)
{
m_stats_counters.inc_stats_counter(counters::num_peers_up_unchoked_optimistic, -1);
</pre></td></tr><tr style="background: #fcc"><td>relevance&nbsp;3</td><td><a href="javascript:expand(7)">../src/torrent.cpp:9593</a></td><td>this really needs to be moved to do_async_save_resume_data. flags need to be passed on</td></tr><tr id="7" style="display: none;" colspan="3"><td colspan="3"><h2>this really needs to be moved to do_async_save_resume_data.
flags need to be passed on</h2><h4>../src/torrent.cpp:9593</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> alerts().emplace_alert&lt;save_resume_data_failed_alert&gt;(get_handle()
</pre></td></tr><tr style="background: #fcc"><td>relevance&nbsp;3</td><td><a href="javascript:expand(7)">../src/torrent.cpp:9611</a></td><td>this really needs to be moved to do_async_save_resume_data. flags need to be passed on</td></tr><tr id="7" style="display: none;" colspan="3"><td colspan="3"><h2>this really needs to be moved to do_async_save_resume_data.
flags need to be passed on</h2><h4>../src/torrent.cpp:9611</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> alerts().emplace_alert&lt;save_resume_data_failed_alert&gt;(get_handle()
, m_error);
return;
}
@ -2579,9 +2579,9 @@ session host resolver interface</h2><h4>../src/torrent.cpp:4941</h4><pre style="
// disable super seeding for all peers
for (peer_iterator i = begin(); i != end(); ++i)
{
</pre></td></tr><tr style="background: #cfc"><td>relevance&nbsp;2</td><td><a href="javascript:expand(52)">../src/torrent.cpp:8109</a></td><td>if peer is a really good peer, maybe we shouldn't disconnect it perhaps this logic should be disabled if we have too many idle peers (with some definition of idle)</td></tr><tr id="52" style="display: none;" colspan="3"><td colspan="3"><h2>if peer is a really good peer, maybe we shouldn't disconnect it
</pre></td></tr><tr style="background: #cfc"><td>relevance&nbsp;2</td><td><a href="javascript:expand(52)">../src/torrent.cpp:8127</a></td><td>if peer is a really good peer, maybe we shouldn't disconnect it perhaps this logic should be disabled if we have too many idle peers (with some definition of idle)</td></tr><tr id="52" style="display: none;" colspan="3"><td colspan="3"><h2>if peer is a really good peer, maybe we shouldn't disconnect it
perhaps this logic should be disabled if we have too many idle peers
(with some definition of idle)</h2><h4>../src/torrent.cpp:8109</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;">#ifndef TORRENT_DISABLE_LOGGING
(with some definition of idle)</h2><h4>../src/torrent.cpp:8127</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;">#ifndef TORRENT_DISABLE_LOGGING
debug_log("incoming peer (%d)", int(m_connections.size()));
#endif
@ -4341,9 +4341,9 @@ it may pose an issue when downgrading though</h2><h4>../src/torrent.cpp:7227</h4
// write have bitmask
// the pieces string has one byte per piece. Each
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(87)">../src/torrent.cpp:8453</a></td><td>should disconnect all peers that have the pieces we have not just seeds. It would be pretty expensive to check all pieces for all peers though</td></tr><tr id="87" style="display: none;" colspan="3"><td colspan="3"><h2>should disconnect all peers that have the pieces we have
</pre></td></tr><tr style="background: #ccf"><td>relevance&nbsp;1</td><td><a href="javascript:expand(87)">../src/torrent.cpp:8471</a></td><td>should disconnect all peers that have the pieces we have not just seeds. It would be pretty expensive to check all pieces for all peers though</td></tr><tr id="87" style="display: none;" colspan="3"><td colspan="3"><h2>should disconnect all peers that have the pieces we have
not just seeds. It would be pretty expensive to check all pieces
for all peers though</h2><h4>../src/torrent.cpp:8453</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;">
for all peers though</h2><h4>../src/torrent.cpp:8471</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;">
set_state(torrent_status::finished);
set_queue_position(-1);
@ -8392,25 +8392,25 @@ no one uses merkle torrents</h2><h4>../src/torrent.cpp:7059</h4><pre style="back
if (piece_priority &amp;&amp; piece_priority.string_length()
== m_torrent_file-&gt;num_pieces())
{
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(222)">../src/torrent.cpp:7285</a></td><td>make this more generic to not just work if files have been renamed, but also if they have been merged into a single file for instance. using file_base</td></tr><tr id="222" style="display: none;" colspan="3"><td colspan="3"><h2>make this more generic to not just work if files have been
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(222)">../src/torrent.cpp:7303</a></td><td>make this more generic to not just work if files have been renamed, but also if they have been merged into a single file for instance. using file_base</td></tr><tr id="222" style="display: none;" colspan="3"><td colspan="3"><h2>make this more generic to not just work if files have been
renamed, but also if they have been merged into a single file for instance.
using file_base</h2><h4>../src/torrent.cpp:7285</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> pieces.resize(m_torrent_file-&gt;num_pieces());
if (!has_picker())
{
std::memset(&amp;pieces[0], m_have_all, pieces.size());
}
else if (has_picker())
{
for (int i = 0, end(pieces.size()); i &lt; end; ++i)
pieces[i] = m_picker-&gt;have_piece(i) ? 1 : 0;
}
using file_base</h2><h4>../src/torrent.cpp:7303</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> if (!has_picker())
{
std::memset(&amp;pieces[0], m_have_all, pieces.size());
}
else if (has_picker())
{
for (int i = 0, end(pieces.size()); i &lt; end; ++i)
pieces[i] = m_picker-&gt;have_piece(i) ? 1 : 0;
}
if (m_seed_mode)
{
TORRENT_ASSERT(m_verified.size() == pieces.size());
TORRENT_ASSERT(m_verifying.size() == pieces.size());
for (int i = 0, end(pieces.size()); i &lt; end; ++i)
pieces[i] |= m_verified[i] ? 2 : 0;
if (m_seed_mode)
{
TORRENT_ASSERT(m_verified.size() == pieces.size());
TORRENT_ASSERT(m_verifying.size() == pieces.size());
for (int i = 0, end(pieces.size()); i &lt; end; ++i)
pieces[i] |= m_verified[i] ? 2 : 0;
}
}
// write renamed files
@ -8445,9 +8445,9 @@ using file_base</h2><h4>../src/torrent.cpp:7285</h4><pre style="background: #f6f
{
error_code ec;
torrent_peer const* p = *i;
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(223)">../src/torrent.cpp:9541</a></td><td>add a flag to ignore stats, and only care about resume data for content. For unchanged files, don't trigger a load of the metadata just to save an empty resume data file</td></tr><tr id="223" style="display: none;" colspan="3"><td colspan="3"><h2>add a flag to ignore stats, and only care about resume data for
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(223)">../src/torrent.cpp:9559</a></td><td>add a flag to ignore stats, and only care about resume data for content. For unchanged files, don't trigger a load of the metadata just to save an empty resume data file</td></tr><tr id="223" style="display: none;" colspan="3"><td colspan="3"><h2>add a flag to ignore stats, and only care about resume data for
content. For unchanged files, don't trigger a load of the metadata
just to save an empty resume data file</h2><h4>../src/torrent.cpp:9541</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> if (m_complete != 0xffffff) seeds = m_complete;
just to save an empty resume data file</h2><h4>../src/torrent.cpp:9559</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> if (m_complete != 0xffffff) seeds = m_complete;
else seeds = m_peer_list ? m_peer_list-&gt;num_seeds() : 0;
if (m_incomplete != 0xffffff) downloaders = m_incomplete;
@ -8466,7 +8466,7 @@ just to save an empty resume data file</h2><h4>../src/torrent.cpp:9541</h4><pre
return ret;
}
// this is an async operation triggered by the client
// this is an async operation triggered by the client
<div style="background: #ffff00" width="100%"> void torrent::save_resume_data(int flags)
</div> {
TORRENT_ASSERT(is_single_thread());
@ -8498,8 +8498,8 @@ just to save an empty resume data file</h2><h4>../src/torrent.cpp:9541</h4><pre
{
alerts().emplace_alert&lt;save_resume_data_failed_alert&gt;(get_handle()
, m_error);
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(224)">../src/torrent.cpp:11168</a></td><td>instead of resorting the whole list, insert the peers directly into the right place</td></tr><tr id="224" style="display: none;" colspan="3"><td colspan="3"><h2>instead of resorting the whole list, insert the peers
directly into the right place</h2><h4>../src/torrent.cpp:11168</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> printf("timed out [average-piece-time: %d ms ]\n"
</pre></td></tr><tr style="background: #ccc"><td>relevance&nbsp;0</td><td><a href="javascript:expand(224)">../src/torrent.cpp:11186</a></td><td>instead of resorting the whole list, insert the peers directly into the right place</td></tr><tr id="224" style="display: none;" colspan="3"><td colspan="3"><h2>instead of resorting the whole list, insert the peers
directly into the right place</h2><h4>../src/torrent.cpp:11186</h4><pre style="background: #f6f6f6; border: solid 1px #ddd;"> printf("timed out [average-piece-time: %d ms ]\n"
, m_average_piece_time);
#endif
}