documentation update
This commit is contained in:
Arvid Norberg
parent
fe714b4b89
commit
855e6bc345
|
|
@ -3,7 +3,7 @@
|
|||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<title>libtorrent manual</title>
|
||||
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
||||
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
|
||||
|
|
@ -36,19 +36,21 @@
|
|||
<col class="docinfo-content" />
|
||||
<tbody valign="top">
|
||||
<tr><th class="docinfo-name">Author:</th>
|
||||
<td>Arvid Norberg, <a class="last reference" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
||||
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
||||
<tr><th class="docinfo-name">Version:</th>
|
||||
<td>0.15.0</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="contents topic" id="table-of-contents">
|
||||
<p class="topic-title first">Table of contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference" href="#downloading-and-building" id="id9">downloading and building</a><ul>
|
||||
<li><a class="reference" href="#building-from-svn" id="id10">building from svn</a></li>
|
||||
<li><a class="reference" href="#building-with-bbv2" id="id11">building with BBv2</a></li>
|
||||
<li><a class="reference" href="#building-with-autotools" id="id12">building with autotools</a></li>
|
||||
<li><a class="reference" href="#building-with-other-build-systems" id="id13">building with other build systems</a></li>
|
||||
<li><a class="reference" href="#build-configurations" id="id14">build configurations</a></li>
|
||||
<li><a class="reference" href="#building-openssl-for-windows" id="id15">building openssl for windows</a></li>
|
||||
<li><a class="reference internal" href="#downloading-and-building" id="id9">downloading and building</a><ul>
|
||||
<li><a class="reference internal" href="#building-from-svn" id="id10">building from svn</a></li>
|
||||
<li><a class="reference internal" href="#building-with-bbv2" id="id11">building with BBv2</a></li>
|
||||
<li><a class="reference internal" href="#building-with-autotools" id="id12">building with autotools</a></li>
|
||||
<li><a class="reference internal" href="#building-with-other-build-systems" id="id13">building with other build systems</a></li>
|
||||
<li><a class="reference internal" href="#build-configurations" id="id14">build configurations</a></li>
|
||||
<li><a class="reference internal" href="#building-openssl-for-windows" id="id15">building openssl for windows</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
|
@ -56,12 +58,12 @@
|
|||
<div class="section" id="downloading-and-building">
|
||||
<h1>downloading and building</h1>
|
||||
<p>To acquire the latest version of libtorrent, you'll have to grab it from SVN.
|
||||
You'll find instructions on how to do this <a class="reference" href="http://sourceforge.net/svn/?group_id=79942">here</a> (see subversion access).</p>
|
||||
You'll find instructions on how to do this <a class="reference external" href="http://sourceforge.net/svn/?group_id=79942">here</a> (see subversion access).</p>
|
||||
<p>The build systems supported "out of the box" in libtorrent are boost-build v2
|
||||
(BBv2) and autotools (for unix-like systems). If you still can't build after
|
||||
following these instructions, you can usually get help in the <tt class="docutils literal"><span class="pre">#libtorrent</span></tt>
|
||||
IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
|
||||
<p>Community contributed build tutorials can be found on the <a class="reference" href="http://code.rasterbar.com/libtorrent/wiki/Building">wiki</a>.</p>
|
||||
<p>Community contributed build tutorials can be found on the <a class="reference external" href="http://code.rasterbar.com/libtorrent/wiki/Building">wiki</a>.</p>
|
||||
<div class="section" id="building-from-svn">
|
||||
<h2>building from svn</h2>
|
||||
<p>To build libtorrent from svn you need to check out the libtorrent sources from
|
||||
|
|
@ -69,8 +71,8 @@ sourceforge and also check out the asio sources from its sourceforge cvs.
|
|||
If you downloaded a release tarball, you can skip this section.</p>
|
||||
<p>To prepare the directory structure for building, follow these steps:</p>
|
||||
<ul class="simple">
|
||||
<li>Check out libtorrent (<a class="reference" href="http://sourceforge.net/svn/?group_id=79942">instructions</a>).</li>
|
||||
<li>Check out asio (<a class="reference" href="http://sourceforge.net/cvs/?group_id=122478">instructions</a>).</li>
|
||||
<li>Check out libtorrent (<a class="reference external" href="http://sourceforge.net/svn/?group_id=79942">instructions</a>).</li>
|
||||
<li>Check out asio (<a class="reference external" href="http://sourceforge.net/cvs/?group_id=122478">instructions</a>).</li>
|
||||
<li>Copy the <tt class="docutils literal"><span class="pre">asio/include/asio/</span></tt> directory into the <tt class="docutils literal"><span class="pre">libtorrent/include/libtorrent/</span></tt>
|
||||
directory. Alternatively you can make a symbolic link.</li>
|
||||
<li>Copy <tt class="docutils literal"><span class="pre">asio/include/asio.hpp</span></tt> into <tt class="docutils literal"><span class="pre">libtorrent/include/libtorrent</span></tt>.</li>
|
||||
|
|
@ -82,7 +84,7 @@ of the following sections depending on which build system you prefer to use.</p>
|
|||
<h2>building with BBv2</h2>
|
||||
<p>The primary reason to use boost-build is that it will automatically build the
|
||||
dependent boost libraries with the correct compiler settings, in order to
|
||||
ensure that the build targets are link compatible (see <a class="reference" href="http://boost.org/more/separate_compilation.html">boost guidelines</a>
|
||||
ensure that the build targets are link compatible (see <a class="reference external" href="http://boost.org/more/separate_compilation.html">boost guidelines</a>
|
||||
for some details on this issue).</p>
|
||||
<p>Since BBv2 will build the boost libraries for you, you need the full boost
|
||||
source package. Having boost installed via some package system is usually not
|
||||
|
|
@ -92,7 +94,7 @@ usually not set by the package installer).</p>
|
|||
to step 3 (assuming you also have boost build installed).</p>
|
||||
<div class="section" id="step-1-download-boost">
|
||||
<h3>Step 1: Download boost</h3>
|
||||
<p>You'll find boost <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=619445">here</a>.</p>
|
||||
<p>You'll find boost <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=619445">here</a>.</p>
|
||||
<p>Extract the archive to some directory where you want it. For the sake of this
|
||||
guide, let's assume you extract the package to <tt class="docutils literal"><span class="pre">c:\boost_1_34_0</span></tt> (I'm using
|
||||
a windows path in this example since if you're on linux/unix you're more likely
|
||||
|
|
@ -150,7 +152,7 @@ using darwin : 3.3 : g++-3.3 ;
|
|||
using darwin : 4.0 : g++-4.0 ;
|
||||
</pre>
|
||||
<p>Note that the spaces around the semi-colons and colons are important!</p>
|
||||
<p>Also see the <a class="reference" href="http://www.boost.org/doc/html/bbv2/installation.html">official installation instructions</a>.</p>
|
||||
<p>Also see the <a class="reference external" href="http://www.boost.org/doc/html/bbv2/installation.html">official installation instructions</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="step-3-building-libtorrent">
|
||||
<h3>Step 3: Building libtorrent</h3>
|
||||
|
|
@ -202,6 +204,11 @@ the POSIX clock functions. If you get an error complaining about a missing
|
|||
symbol <tt class="docutils literal"><span class="pre">clock_gettime</span></tt>, you have to give <tt class="docutils literal"><span class="pre">need-librt=yes</span></tt> on the
|
||||
bjam command line. This will make libtorrent link against <tt class="docutils literal"><span class="pre">librt</span></tt>.</p>
|
||||
</div>
|
||||
<div class="note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">When building on Solaris, you might have to specify <tt class="docutils literal"><span class="pre">stdlib=sun-stlport</span></tt>
|
||||
on the bjam command line.</p>
|
||||
</div>
|
||||
<p>The build targets are put in a directory called bin, and under it they are
|
||||
sorted in directories depending on the toolset and build variant used.</p>
|
||||
<p>To build the examples, just change directory to the examples directory and
|
||||
|
|
@ -215,7 +222,7 @@ Also, make sure the paths are correct in the different environments. In cygwin,
|
|||
<tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_34_0</span></tt>). In the windows environment, they should have the typical
|
||||
windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_34_0</span></tt>).</p>
|
||||
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> will define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> when it's building a release build.
|
||||
For more build configuration flags see <a class="reference" href="#build-configurations">Build configurations</a>.</p>
|
||||
For more build configuration flags see <a class="reference internal" href="#build-configurations">Build configurations</a>.</p>
|
||||
<p>Build features:</p>
|
||||
<table border="1" class="docutils">
|
||||
<colgroup>
|
||||
|
|
@ -290,10 +297,10 @@ with the libtorrent package.</li>
|
|||
<tr><td><tt class="docutils literal"><span class="pre">geoip</span></tt></td>
|
||||
<td><ul class="first last simple">
|
||||
<li><tt class="docutils literal"><span class="pre">off</span></tt> - geo ip lookups disabled</li>
|
||||
<li><tt class="docutils literal"><span class="pre">static</span></tt> - <a class="reference" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup code linked
|
||||
<li><tt class="docutils literal"><span class="pre">static</span></tt> - <a class="reference external" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup code linked
|
||||
in statically. Note that this code is under
|
||||
LGPL license.</li>
|
||||
<li><tt class="docutils literal"><span class="pre">shared</span></tt> - The <a class="reference" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup library
|
||||
<li><tt class="docutils literal"><span class="pre">shared</span></tt> - The <a class="reference external" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup library
|
||||
is expected to be installed on the system and
|
||||
it will be used.</li>
|
||||
</ul>
|
||||
|
|
@ -415,8 +422,8 @@ the name of the feature, just the value.</p>
|
|||
<p>When building the example client on windows, you need to build with
|
||||
<tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some
|
||||
boost.program-options symbols.</p>
|
||||
<p>For more information, see the <a class="reference" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>, or more
|
||||
specifically <a class="reference" href="http://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features">the section on builtin features</a>.</p>
|
||||
<p>For more information, see the <a class="reference external" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>, or more
|
||||
specifically <a class="reference external" href="http://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features">the section on builtin features</a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="building-with-autotools">
|
||||
|
|
@ -435,7 +442,7 @@ and boost.program_options.</p>
|
|||
<h3>Step 1: Generating the build system</h3>
|
||||
<p>No build system is present if libtorrent is checked out from CVS - it
|
||||
needs to be generated first. If you're building from a released tarball,
|
||||
you may skip directly to <a class="reference" href="#step-2-running-configure">Step 2: Running configure</a>.</p>
|
||||
you may skip directly to <a class="reference internal" href="#step-2-running-configure">Step 2: Running configure</a>.</p>
|
||||
<p>Execute the following commands, in the given order, to generate
|
||||
the build system:</p>
|
||||
<pre class="literal-block">
|
||||
|
|
@ -544,7 +551,7 @@ filenames, so if your target is Windows 2000 and up, you may want to use
|
|||
<p>If you're building in MS Visual Studio, you may have to set the compiler
|
||||
options "force conformance in for loop scope", "treat wchar_t as built-in
|
||||
type" and "Enable Run-Time Type Info" to Yes. For a detailed description
|
||||
on how to build libtorrent with VS, see <a class="reference" href="http://code.rasterbar.com/libtorrent/wiki/Building">the wiki</a>.</p>
|
||||
on how to build libtorrent with VS, see <a class="reference external" href="http://code.rasterbar.com/libtorrent/wiki/Building">the wiki</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="build-configurations">
|
||||
<h2>build configurations</h2>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<title>libtorrent manual</title>
|
||||
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
||||
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
|
||||
|
|
@ -36,105 +36,190 @@
|
|||
<col class="docinfo-content" />
|
||||
<tbody valign="top">
|
||||
<tr><th class="docinfo-name">Author:</th>
|
||||
<td>Arvid Norberg, <a class="last reference" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
||||
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
||||
<tr><th class="docinfo-name">Version:</th>
|
||||
<td>0.15.0</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="contents topic" id="table-of-contents">
|
||||
<p class="topic-title first">Table of contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference" href="#introduction" id="id2">introduction</a></li>
|
||||
<li><a class="reference" href="#features" id="id3">features</a></li>
|
||||
<li><a class="reference" href="#portability" id="id4">portability</a></li>
|
||||
<li><a class="reference" href="#license" id="id5">license</a></li>
|
||||
<li><a class="reference internal" href="#introduction" id="id2">introduction</a></li>
|
||||
<li><a class="reference internal" href="#features" id="id3">features</a><ul>
|
||||
<li><a class="reference internal" href="#extensions" id="id4">extensions</a></li>
|
||||
<li><a class="reference internal" href="#disk-management" id="id5">disk management</a></li>
|
||||
<li><a class="reference internal" href="#network" id="id6">network</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#highlighted-features" id="id7">highlighted features</a><ul>
|
||||
<li><a class="reference internal" href="#disk-caching" id="id8">disk caching</a></li>
|
||||
<li><a class="reference internal" href="#network-buffers" id="id9">network buffers</a></li>
|
||||
<li><a class="reference internal" href="#piece-picker" id="id10">piece picker</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#portability" id="id11">portability</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="introduction">
|
||||
<h1>introduction</h1>
|
||||
<p>libtorrent is a C++ library that aims to be a good alternative to all the
|
||||
other bittorrent implementations around. It is a
|
||||
library and not a full featured client, although it comes with a working
|
||||
example client.</p>
|
||||
<p>The main goals of libtorrent are:</p>
|
||||
<ul class="simple">
|
||||
<li>to be cpu efficient</li>
|
||||
<li>to be memory efficient</li>
|
||||
<li>to be very easy to use</li>
|
||||
</ul>
|
||||
<p>libtorrent is a feature complete C++ bittorrent implementation focusing
|
||||
on efficiency and scalability. It runs on embedded devices as well as
|
||||
desktops. It boasts a well documented library interface that is easy to
|
||||
use. It comes with a simple bittorrent client demonstrating the use of
|
||||
the library.</p>
|
||||
</div>
|
||||
<div class="section" id="features">
|
||||
<h1>features</h1>
|
||||
<p>libtorrent is still being developed, however it is stable. It is an ongoing
|
||||
project (including this documentation). The current state includes the
|
||||
following features:</p>
|
||||
<p>libtorrent is under active development. It is an ongoing project. Its
|
||||
current state supports and includes the following features:</p>
|
||||
<div class="section" id="extensions">
|
||||
<h2>extensions</h2>
|
||||
<ul class="simple">
|
||||
<li>trackerless torrents (using the Mainline kademlia DHT protocol) with
|
||||
some <a class="reference" href="dht_extensions.html">DHT extensions</a>. <a class="reference" href="http://bittorrent.org/beps/bep_0005.html">BEP 5</a>.</li>
|
||||
<li>support for IPv6, including <a class="reference" href="http://bittorrent.org/beps/bep_0007.html">BEP 7</a> and <a class="reference" href="http://bittorrent.org/beps/bep_0024.html">BEP 24</a>.</li>
|
||||
<li>NAT-PMP and UPnP support (automatic port mapping on routers that supports it)</li>
|
||||
<li>uses a separate disk I/O thread to not have the disk ever block on network or
|
||||
client interaction. (see <a class="reference" href="manual.html#threads">threads</a>).</li>
|
||||
<li>supports the bittorrent <a class="reference" href="extension_protocol.html">extension protocol</a>. See <a class="reference" href="manual.html#extensions">extensions</a>. <a class="reference" href="http://bittorrent.org/beps/bep_0010.html">BEP 10</a>.</li>
|
||||
<li>plugin interface for implementing custom bittorrent extensions
|
||||
without having to modify libtorrent</li>
|
||||
<li>supports trackerless torrents (using the Mainline kademlia DHT protocol) with
|
||||
some <a class="reference external" href="dht_extensions.html">DHT extensions</a>. <a class="reference external" href="http://bittorrent.org/beps/bep_0005.html">BEP 5</a>.</li>
|
||||
<li>supports the bittorrent <a class="reference external" href="extension_protocol.html">extension protocol</a>. See <a class="reference external" href="manual.html#extensions">extensions</a>. <a class="reference external" href="http://bittorrent.org/beps/bep_0010.html">BEP 10</a>.</li>
|
||||
<li>supports the uTorrent metadata transfer protocol (i.e. magnet links).</li>
|
||||
<li>supports the uTorrent peer exchange protocol (PEX).</li>
|
||||
<li>supports local peer discovery (multicasts for peers on the same local network)</li>
|
||||
<li>adjusts the length of the request queue depending on download rate.</li>
|
||||
<li>has an adjustable read and write disk cache for improved disk throughput.</li>
|
||||
<li>multitracker extension support (supports both strict <a class="reference" href="http://bittorrent.org/beps/bep_0012.html">BEP 12</a> and the
|
||||
<li>multitracker extension support (supports both strict <a class="reference external" href="http://bittorrent.org/beps/bep_0012.html">BEP 12</a> and the
|
||||
uTorrent interpretation).</li>
|
||||
<li>tracker scrapes</li>
|
||||
<li>supports lt_trackers extension, to exchange trackers between peers</li>
|
||||
<li>supports both sparse files and compact file allocation (where pieces
|
||||
are kept consolidated on disk)</li>
|
||||
<li>super seeding/initial seeding (<a class="reference" href="http://bittorrent.org/beps/bep_0016.html">BEP 16</a>).</li>
|
||||
<li><a class="reference external" href="manual.html#http-seeding">HTTP seeding</a>, as specified in <a class="reference external" href="http://bittorrent.org/beps/bep_0017.html">BEP 17</a> and <a class="reference external" href="http://bittorrent.org/beps/bep_0019.html">BEP 19</a>.</li>
|
||||
<li>supports the udp-tracker protocol. (<a class="reference external" href="http://bittorrent.org/beps/bep_0015.html">BEP 15</a>).</li>
|
||||
<li>supports the <tt class="docutils literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li>
|
||||
<li>supports the <tt class="docutils literal"><span class="pre">compact=1</span></tt> tracker parameter.</li>
|
||||
<li>super seeding/initial seeding (<a class="reference external" href="http://bittorrent.org/beps/bep_0016.html">BEP 16</a>).</li>
|
||||
<li>private torrents (<a class="reference external" href="http://bittorrent.org/beps/bep_0027.html">BEP 27</a>).</li>
|
||||
<li>support for IPv6, including <a class="reference external" href="http://bittorrent.org/beps/bep_0007.html">BEP 7</a> and <a class="reference external" href="http://bittorrent.org/beps/bep_0024.html">BEP 24</a>.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<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="manual.html#threads">threads</a>).</li>
|
||||
<li>supports files > 2 gigabytes.</li>
|
||||
<li>serves multiple torrents on a single port and in a single thread</li>
|
||||
<li>fast resume support, a way to get rid of 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>
|
||||
<li><a class="reference" href="manual.html#http-seeding">HTTP seeding</a>, as specified in <a class="reference" href="http://bittorrent.org/beps/bep_0017.html">BEP 17</a> and <a class="reference" href="http://bittorrent.org/beps/bep_0019.html">BEP 19</a>.</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>supports both sparse files and compact file allocation (where pieces
|
||||
are kept consolidated on disk)</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>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="network">
|
||||
<h2>network</h2>
|
||||
<ul class="simple">
|
||||
<li>adjusts the length of the request queue depending on download rate.</li>
|
||||
<li>serves multiple torrents on a single port and in a single thread</li>
|
||||
<li>piece picking on block-level (as opposed to piece-level).
|
||||
This means it can download parts of the same piece from different peers.
|
||||
It will also prefer to download whole pieces from single peers if the
|
||||
download speed is high enough from that particular peer.</li>
|
||||
<li>supports the udp-tracker protocol. (<a class="reference" href="http://bittorrent.org/beps/bep_0015.html">BEP 15</a>).</li>
|
||||
<li>queues torrents for file check, instead of checking all of them in parallel.</li>
|
||||
<li>supports http proxies and basic proxy authentication</li>
|
||||
<li>gzipped tracker-responses</li>
|
||||
<li>supports gzipped tracker-responses</li>
|
||||
<li>can limit the upload and download bandwidth usage and the maximum number of
|
||||
unchoked peers</li>
|
||||
<li>implements fair trade. User settable trade-ratio, must at least be 1:1,
|
||||
but one can choose to trade 1 for 2 or any other ratio that isn't unfair
|
||||
to the other party.</li>
|
||||
<li>supports the <tt class="docutils literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li>
|
||||
<li>possibility to limit the number of connections.</li>
|
||||
<li>delays have messages if there's no other outgoing traffic to the peer, and
|
||||
doesn't send have messages to peers that already has the piece. This saves
|
||||
bandwidth.</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>supports the <tt class="docutils literal"><span class="pre">compact=1</span></tt> tracker parameter.</li>
|
||||
<li>selective downloading. The ability to select which parts of a torrent you
|
||||
want to download.</li>
|
||||
<li>ip filter to disallow ip addresses and ip ranges from connecting and
|
||||
being connected</li>
|
||||
<li>private torrents (<a class="reference" href="http://bittorrent.org/beps/bep_0027.html">BEP 27</a>).</li>
|
||||
<li>NAT-PMP and UPnP support (automatic port mapping on routers that supports it)</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="highlighted-features">
|
||||
<h1>highlighted features</h1>
|
||||
<div class="section" id="disk-caching">
|
||||
<h2>disk caching</h2>
|
||||
<p>All disk I/O in libtorrent is done asynchronously to the network thread, by the
|
||||
disk io thread. When a block is read, the disk io thread reads all subsequent
|
||||
blocks from that piece into the read cache, assuming that the peer requesting
|
||||
the block will also request more blocks from the same piece. This decreases the
|
||||
number of syscalls for reading data. It also decreases delay from seeking.</p>
|
||||
<p>Similarly, for write requests, blocks are cached and flushed to disk once one full
|
||||
piece is complete or the piece is the least recently updated one when more cache
|
||||
space is needed. The cache dynamically allocates space between the write and read
|
||||
cache. The write cache is strictly prioritized over the read cache.</p>
|
||||
<p>The cache blocks that are in used, are locked into physical memory to avoid it
|
||||
being paged out to disk. Allowing the disk cache to be paged out to disk means
|
||||
that it would become extremely inefficient to flush it, since it would have to be
|
||||
read back into physical memory only to be flushed back out to disk again.</p>
|
||||
<p>In order to conserve memory, and system calls, iovec file operations are
|
||||
used to flush multiple cache blocks in a single call.</p>
|
||||
<p>On low-memory systems, the disk cache can be disabled altogether or set to smaller
|
||||
limit, to save memory.</p>
|
||||
</div>
|
||||
<div class="section" id="network-buffers">
|
||||
<h2>network buffers</h2>
|
||||
<p>On CPUs with small L2 caches, copying memory can be expensive operations. It is important
|
||||
to keep copying to a minimum on such machines. This mostly applies to embedded systems.</p>
|
||||
<p>In order to minimize the number of times received data is copied, the receive buffer
|
||||
for payload data is received directly into a page aligned disk buffer. If the connection
|
||||
is encrypted, the buffer is decrypted in-place. The buffer is then moved into the disk
|
||||
cache without being copied. Once all the blocks for a piece have been received, or the
|
||||
cache needs to be flushed, all the blocks are passed directly to <tt class="docutils literal"><span class="pre">writev()</span></tt> to flush
|
||||
them in a single syscall. This means a single copy into user space memory, and a single
|
||||
copy back into kernel memory, as illustrated by this figure:</p>
|
||||
<img alt="write_disk_buffers.png" src="write_disk_buffers.png" style="width: 100%;" />
|
||||
<p>When seeding and uploading in general, unnecessary copying is avoided by caching blocks
|
||||
in aligned buffers, that are copied once into the peer's send buffer. The peer's send buffer
|
||||
is not guaranteed to be aligned, even though it is most of the time. The send buffer is
|
||||
then encrypted with the peer specific key and chained onto the <tt class="docutils literal"><span class="pre">iovec</span></tt> for sending.
|
||||
This means there is one user space copy in order to allow unaligned peer requests and
|
||||
peer-specific encryption. This is illustrated by the following figure:</p>
|
||||
<img alt="read_disk_buffers.png" src="read_disk_buffers.png" style="width: 100%;" />
|
||||
</div>
|
||||
<div class="section" id="piece-picker">
|
||||
<h2>piece picker</h2>
|
||||
<p>The piece picker is a central component in a bittorrent implementation. The piece picker
|
||||
in libtorrent is optimized for quickly finding the rarest pieces. It keeps a list of all
|
||||
available pieces sorted by rarity, and pieces with the same rarity, shuffled. The rarest
|
||||
first mode is the dominant piece picker mode. Other modes are supported as well, and
|
||||
used by peers in specific situations.</p>
|
||||
<p>The piece picker allows to combine the availability of a piece with a priority. Together
|
||||
they determine the sort order of the piece list. Pieces with priority 0 will never be
|
||||
picked, which is used for the selective download feature.</p>
|
||||
<p>In order to have as few partially finished pieces as possible, peers have an affinity
|
||||
towards picking blocks from the same pieces as other peers in the same speed category.
|
||||
The speed category is a coarse categorization of peers based on their download rate. This
|
||||
makes slow peers pick blocks from the same piece, and fast peers pick from the same piece,
|
||||
and hence decreasing the likelihood of slow peers blocking the completion of pieces.</p>
|
||||
<p>The piece picker can also be set to download pieces in sequential order.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="portability">
|
||||
<h1>portability</h1>
|
||||
<p>libtorrent is portable at least among Windows, MacOS X and other UNIX-systems.
|
||||
<p>libtorrent runs on most major operating systems, including Windows,
|
||||
MacOS X, Linux, BSD and Solaris.
|
||||
It uses Boost.Thread, Boost.Filesystem, Boost.Date_time and various other
|
||||
boost libraries as well as <a class="reference" href="http://www.zlib.org">zlib</a> (shipped) and <a class="reference" href="http://asio.sf.net">asio</a> (shipped). At least version
|
||||
boost libraries as well as <a class="reference external" href="http://www.zlib.org">zlib</a> (shipped) and <a class="reference external" href="http://asio.sf.net">asio</a> (shipped). At least version
|
||||
1.34.1 of boost is required.</p>
|
||||
<p>Since libtorrent uses asio, it will take full advantage of high performance
|
||||
<p>libtorrent uses asio, hence it will take full advantage of high performance
|
||||
network APIs on the most popular platforms. I/O completion ports on windows,
|
||||
epoll on linux and kqueue on MacOS X and BSD.</p>
|
||||
<p>libtorrent has been successfully compiled and tested on:</p>
|
||||
<ul class="simple">
|
||||
<li>Windows 2000 vc7.1, vc8</li>
|
||||
<li>Linux x86 GCC 3.3, GCC 3.4.2</li>
|
||||
<li>Windows 2000, XP and Vista vc7.1, vc8</li>
|
||||
<li>Linux x86 GCC 3.3, GCC 3.4.2, 4.x</li>
|
||||
<li>Linux PPC GCC 4.1.1</li>
|
||||
<li>MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0</li>
|
||||
<li>SunOS 5.8 GCC 3.1</li>
|
||||
<li>SunOS 5.8 GCC 3.1 and Sunpro</li>
|
||||
<li>Cygwin GCC 3.3.3</li>
|
||||
</ul>
|
||||
<p>Fails on:</p>
|
||||
|
|
@ -142,15 +227,6 @@ epoll on linux and kqueue on MacOS X and BSD.</p>
|
|||
<li>GCC 2.95.4</li>
|
||||
<li>msvc6</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="license">
|
||||
<h1>license</h1>
|
||||
<p>libtorrent is released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
|
||||
<p>This means that you can use the library in your project without having to
|
||||
release its source code. The only requirement is that you give credit
|
||||
to the author of the library by including the libtorrent license in your
|
||||
software or documentation.</p>
|
||||
<p><a class="reference" href="projects.html">Here's</a> a list of some projects that uses libtorrent.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footer">
|
||||
|
|
|
|||
|
|
@ -12,75 +12,90 @@ libtorrent manual
|
|||
introduction
|
||||
============
|
||||
|
||||
libtorrent is a C++ library that aims to be a good alternative to all the
|
||||
other bittorrent implementations around. It is a
|
||||
library and not a full featured client, although it comes with a working
|
||||
example client.
|
||||
|
||||
The main goals of libtorrent are:
|
||||
|
||||
* to be cpu efficient
|
||||
* to be memory efficient
|
||||
* to be very easy to use
|
||||
libtorrent is a feature complete C++ bittorrent implementation focusing
|
||||
on efficiency and scalability. It runs on embedded devices as well as
|
||||
desktops. It boasts a well documented library interface that is easy to
|
||||
use. It comes with a simple bittorrent client demonstrating the use of
|
||||
the library.
|
||||
|
||||
features
|
||||
========
|
||||
|
||||
libtorrent is still being developed, however it is stable. It is an ongoing
|
||||
project (including this documentation). The current state includes the
|
||||
following features:
|
||||
libtorrent is under active development. It is an ongoing project. Its
|
||||
current state supports and includes the following features:
|
||||
|
||||
* trackerless torrents (using the Mainline kademlia DHT protocol) with
|
||||
extensions
|
||||
----------
|
||||
|
||||
* plugin interface for implementing custom bittorrent extensions
|
||||
without having to modify libtorrent
|
||||
* supports trackerless torrents (using the Mainline kademlia DHT protocol) with
|
||||
some `DHT extensions`_. `BEP 5`_.
|
||||
* support for IPv6, including `BEP 7`_ and `BEP 24`_.
|
||||
* NAT-PMP and UPnP support (automatic port mapping on routers that supports it)
|
||||
* uses a separate disk I/O thread to not have the disk ever block on network or
|
||||
client interaction. (see threads_).
|
||||
* supports the bittorrent `extension protocol`_. See extensions_. `BEP 10`_.
|
||||
* supports the uTorrent metadata transfer protocol (i.e. magnet links).
|
||||
* supports the uTorrent peer exchange protocol (PEX).
|
||||
* supports local peer discovery (multicasts for peers on the same local network)
|
||||
* adjusts the length of the request queue depending on download rate.
|
||||
* has an adjustable read and write disk cache for improved disk throughput.
|
||||
* multitracker extension support (supports both strict `BEP 12`_ and the
|
||||
uTorrent interpretation).
|
||||
* tracker scrapes
|
||||
* supports lt_trackers extension, to exchange trackers between peers
|
||||
* supports both sparse files and compact file allocation (where pieces
|
||||
are kept consolidated on disk)
|
||||
* `HTTP seeding`_, as specified in `BEP 17`_ and `BEP 19`_.
|
||||
* supports the udp-tracker protocol. (`BEP 15`_).
|
||||
* supports the ``no_peer_id=1`` extension that will ease the load off trackers.
|
||||
* supports the ``compact=1`` tracker parameter.
|
||||
* super seeding/initial seeding (`BEP 16`_).
|
||||
* private torrents (`BEP 27`_).
|
||||
* support for IPv6, including `BEP 7`_ and `BEP 24`_.
|
||||
|
||||
.. _extensions: manual.html#extensions
|
||||
.. _`http seeding`: manual.html#http-seeding
|
||||
|
||||
disk management
|
||||
---------------
|
||||
|
||||
* uses a separate disk I/O thread to not have the disk ever block on network or
|
||||
client interaction. (see threads_).
|
||||
* supports files > 2 gigabytes.
|
||||
* serves multiple torrents on a single port and in a single thread
|
||||
* fast resume support, a way to get rid of 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.
|
||||
* `HTTP seeding`_, as specified in `BEP 17`_ and `BEP 19`_.
|
||||
* 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.
|
||||
* supports both sparse files and compact file allocation (where pieces
|
||||
are kept consolidated on disk)
|
||||
* 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: manual.html#threads
|
||||
|
||||
network
|
||||
-------
|
||||
|
||||
* adjusts the length of the request queue depending on download rate.
|
||||
* serves multiple torrents on a single port and in a single thread
|
||||
* piece picking on block-level (as opposed to piece-level).
|
||||
This means it can download parts of the same piece from different peers.
|
||||
It will also prefer to download whole pieces from single peers if the
|
||||
download speed is high enough from that particular peer.
|
||||
* supports the udp-tracker protocol. (`BEP 15`_).
|
||||
* queues torrents for file check, instead of checking all of them in parallel.
|
||||
* supports http proxies and basic proxy authentication
|
||||
* gzipped tracker-responses
|
||||
* supports gzipped tracker-responses
|
||||
* can limit the upload and download bandwidth usage and the maximum number of
|
||||
unchoked peers
|
||||
* implements fair trade. User settable trade-ratio, must at least be 1:1,
|
||||
but one can choose to trade 1 for 2 or any other ratio that isn't unfair
|
||||
to the other party.
|
||||
* supports the ``no_peer_id=1`` extension that will ease the load off trackers.
|
||||
* possibility to limit the number of connections.
|
||||
* delays have messages if there's no other outgoing traffic to the peer, and
|
||||
doesn't send have messages to peers that already has the piece. This saves
|
||||
bandwidth.
|
||||
* 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.
|
||||
* supports the ``compact=1`` tracker parameter.
|
||||
* selective downloading. The ability to select which parts of a torrent you
|
||||
want to download.
|
||||
* ip filter to disallow ip addresses and ip ranges from connecting and
|
||||
being connected
|
||||
* private torrents (`BEP 27`_).
|
||||
* NAT-PMP and UPnP support (automatic port mapping on routers that supports it)
|
||||
|
||||
|
||||
.. _`DHT extensions`: dht_extensions.html
|
||||
.. _`BEP 5`: http://bittorrent.org/beps/bep_0005.html
|
||||
|
|
@ -95,10 +110,90 @@ following features:
|
|||
.. _`BEP 27`: http://bittorrent.org/beps/bep_0027.html
|
||||
.. _`extension protocol`: extension_protocol.html
|
||||
|
||||
highlighted features
|
||||
====================
|
||||
|
||||
disk caching
|
||||
------------
|
||||
|
||||
All disk I/O in libtorrent is done asynchronously to the network thread, by the
|
||||
disk io thread. When a block is read, the disk io thread reads all subsequent
|
||||
blocks from that piece into the read cache, assuming that the peer requesting
|
||||
the block will also request more blocks from the same piece. This decreases the
|
||||
number of syscalls for reading data. It also decreases delay from seeking.
|
||||
|
||||
Similarly, for write requests, blocks are cached and flushed to disk once one full
|
||||
piece is complete or the piece is the least recently updated one when more cache
|
||||
space is needed. The cache dynamically allocates space between the write and read
|
||||
cache. The write cache is strictly prioritized over the read cache.
|
||||
|
||||
The cache blocks that are in used, are locked into physical memory to avoid it
|
||||
being paged out to disk. Allowing the disk cache to be paged out to disk means
|
||||
that it would become extremely inefficient to flush it, since it would have to be
|
||||
read back into physical memory only to be flushed back out to disk again.
|
||||
|
||||
In order to conserve memory, and system calls, iovec file operations are
|
||||
used to flush multiple cache blocks in a single call.
|
||||
|
||||
On low-memory systems, the disk cache can be disabled altogether or set to smaller
|
||||
limit, to save memory.
|
||||
|
||||
|
||||
network buffers
|
||||
---------------
|
||||
|
||||
On CPUs with small L2 caches, copying memory can be expensive operations. It is important
|
||||
to keep copying to a minimum on such machines. This mostly applies to embedded systems.
|
||||
|
||||
In order to minimize the number of times received data is copied, the receive buffer
|
||||
for payload data is received directly into a page aligned disk buffer. If the connection
|
||||
is encrypted, the buffer is decrypted in-place. The buffer is then moved into the disk
|
||||
cache without being copied. Once all the blocks for a piece have been received, or the
|
||||
cache needs to be flushed, all the blocks are passed directly to ``writev()`` to flush
|
||||
them in a single syscall. This means a single copy into user space memory, and a single
|
||||
copy back into kernel memory, as illustrated by this figure:
|
||||
|
||||
.. image:: write_disk_buffers.png
|
||||
:width: 100%
|
||||
|
||||
When seeding and uploading in general, unnecessary copying is avoided by caching blocks
|
||||
in aligned buffers, that are copied once into the peer's send buffer. The peer's send buffer
|
||||
is not guaranteed to be aligned, even though it is most of the time. The send buffer is
|
||||
then encrypted with the peer specific key and chained onto the ``iovec`` for sending.
|
||||
This means there is one user space copy in order to allow unaligned peer requests and
|
||||
peer-specific encryption. This is illustrated by the following figure:
|
||||
|
||||
.. image:: read_disk_buffers.png
|
||||
:width: 100%
|
||||
|
||||
|
||||
piece picker
|
||||
------------
|
||||
|
||||
The piece picker is a central component in a bittorrent implementation. The piece picker
|
||||
in libtorrent is optimized for quickly finding the rarest pieces. It keeps a list of all
|
||||
available pieces sorted by rarity, and pieces with the same rarity, shuffled. The rarest
|
||||
first mode is the dominant piece picker mode. Other modes are supported as well, and
|
||||
used by peers in specific situations.
|
||||
|
||||
The piece picker allows to combine the availability of a piece with a priority. Together
|
||||
they determine the sort order of the piece list. Pieces with priority 0 will never be
|
||||
picked, which is used for the selective download feature.
|
||||
|
||||
In order to have as few partially finished pieces as possible, peers have an affinity
|
||||
towards picking blocks from the same pieces as other peers in the same speed category.
|
||||
The speed category is a coarse categorization of peers based on their download rate. This
|
||||
makes slow peers pick blocks from the same piece, and fast peers pick from the same piece,
|
||||
and hence decreasing the likelihood of slow peers blocking the completion of pieces.
|
||||
|
||||
The piece picker can also be set to download pieces in sequential order.
|
||||
|
||||
|
||||
portability
|
||||
===========
|
||||
|
||||
libtorrent is portable at least among Windows, MacOS X and other UNIX-systems.
|
||||
libtorrent runs on most major operating systems, including Windows,
|
||||
MacOS X, Linux, BSD and Solaris.
|
||||
It uses Boost.Thread, Boost.Filesystem, Boost.Date_time and various other
|
||||
boost libraries as well as zlib_ (shipped) and asio_ (shipped). At least version
|
||||
1.34.1 of boost is required.
|
||||
|
|
@ -106,16 +201,17 @@ boost libraries as well as zlib_ (shipped) and asio_ (shipped). At least version
|
|||
.. _zlib: http://www.zlib.org
|
||||
.. _asio: http://asio.sf.net
|
||||
|
||||
Since libtorrent uses asio, it will take full advantage of high performance
|
||||
libtorrent uses asio, hence it will take full advantage of high performance
|
||||
network APIs on the most popular platforms. I/O completion ports on windows,
|
||||
epoll on linux and kqueue on MacOS X and BSD.
|
||||
|
||||
libtorrent has been successfully compiled and tested on:
|
||||
|
||||
* Windows 2000 vc7.1, vc8
|
||||
* Linux x86 GCC 3.3, GCC 3.4.2
|
||||
* Windows 2000, XP and Vista vc7.1, vc8
|
||||
* Linux x86 GCC 3.3, GCC 3.4.2, 4.x
|
||||
* Linux PPC GCC 4.1.1
|
||||
* MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0
|
||||
* SunOS 5.8 GCC 3.1
|
||||
* SunOS 5.8 GCC 3.1 and Sunpro
|
||||
* Cygwin GCC 3.3.3
|
||||
|
||||
Fails on:
|
||||
|
|
@ -123,23 +219,4 @@ Fails on:
|
|||
* GCC 2.95.4
|
||||
* msvc6
|
||||
|
||||
license
|
||||
=======
|
||||
|
||||
libtorrent is released under the BSD-license_.
|
||||
|
||||
.. _BSD-license: http://www.opensource.org/licenses/bsd-license.php
|
||||
|
||||
This means that you can use the library in your project without having to
|
||||
release its source code. The only requirement is that you give credit
|
||||
to the author of the library by including the libtorrent license in your
|
||||
software or documentation.
|
||||
|
||||
`Here's`__ a list of some projects that uses libtorrent.
|
||||
|
||||
__ projects.html
|
||||
|
||||
.. _`http seeding`: manual.html#http-seeding
|
||||
.. _threads: manual.html#threads
|
||||
.. _extensions: manual.html#extensions
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<title></title>
|
||||
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
|
||||
|
|
@ -32,47 +32,48 @@
|
|||
|
||||
|
||||
<div id="librarySidebar"><ul class="simple">
|
||||
<li><a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=79942">download</a></li>
|
||||
<li><a class="reference" href="features.html">features</a></li>
|
||||
<li><a class="reference" href="building.html">building libtorrent</a></li>
|
||||
<li><a class="reference" href="examples.html">examples</a></li>
|
||||
<li><a class="reference" href="manual.html">api documentation</a></li>
|
||||
<li><a class="reference" href="make_torrent.html">create torrents</a></li>
|
||||
<li><a class="reference" href="running_tests.html">running tests</a></li>
|
||||
<li><a class="reference" href="client_test.png">screenshot</a></li>
|
||||
<li><a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a> (<a class="reference" href="http://dir.gmane.org/gmane.network.bit-torrent.libtorrent">archive</a>)</li>
|
||||
<li><a class="reference" href="projects.html">who's using libtorrent?</a></li>
|
||||
<li><a class="reference" href="http://code.rasterbar.com/libtorrent/newticket">report bugs</a></li>
|
||||
<li><a class="reference" href="http://www.sourceforge.net/projects/libtorrent">sourceforge page</a></li>
|
||||
<li><a class="reference" href="http://code.rasterbar.com/libtorrent">wiki</a></li>
|
||||
<li><a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=79942">download</a></li>
|
||||
<li><a class="reference external" href="features.html">features</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.html">api documentation</a></li>
|
||||
<li><a class="reference external" href="make_torrent.html">create torrents</a></li>
|
||||
<li><a class="reference external" href="running_tests.html">running tests</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>
|
||||
<li><a class="reference external" href="projects.html">who's using libtorrent?</a></li>
|
||||
<li><a class="reference external" href="http://code.rasterbar.com/libtorrent/newticket">report bugs</a></li>
|
||||
<li><a class="reference external" href="http://www.sourceforge.net/projects/libtorrent">sourceforge page</a></li>
|
||||
<li><a class="reference external" href="http://code.rasterbar.com/libtorrent">wiki</a></li>
|
||||
</ul>
|
||||
<hr class="docutils" />
|
||||
<p>Extensions</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference" href="extension_protocol.html">extensions protocol</a></li>
|
||||
<li><a class="reference" href="libtorrent_plugins.html">plugin interface</a></li>
|
||||
<li><a class="reference" href="dht_extensions.html">DHT extensions</a></li>
|
||||
<li><a class="reference" href="udp_tracker_protocol.html">UDP tracker protocol</a></li>
|
||||
<li><a class="reference" href="http://www.getright.com/seedtorrent.html">HTTP seed</a></li>
|
||||
<li><a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">multitracker</a></li>
|
||||
<li><a class="reference external" href="extension_protocol.html">extensions protocol</a></li>
|
||||
<li><a class="reference external" href="libtorrent_plugins.html">plugin interface</a></li>
|
||||
<li><a class="reference external" href="dht_extensions.html">DHT extensions</a></li>
|
||||
<li><a class="reference external" href="udp_tracker_protocol.html">UDP tracker protocol</a></li>
|
||||
<li><a class="reference external" href="http://www.getright.com/seedtorrent.html">HTTP seed</a></li>
|
||||
<li><a class="reference external" href="http://home.elp.rr.com/tur/multitracker-spec.txt">multitracker</a></li>
|
||||
</ul>
|
||||
<hr class="docutils" />
|
||||
<p>Bindings</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference" href="http://libtorrent-ruby.rubyforge.org/">ruby bindings</a></li>
|
||||
<li><a class="reference" href="python_binding.html">python bindings</a></li>
|
||||
<li><a class="reference external" href="http://libtorrent-ruby.rubyforge.org/">ruby bindings</a></li>
|
||||
<li><a class="reference external" href="python_binding.html">python bindings</a></li>
|
||||
</ul>
|
||||
<hr class="docutils" />
|
||||
<ul class="simple">
|
||||
<li><a class="reference" href="bittorrent.pdf">Introduction, slides</a></li>
|
||||
<li><a class="reference external" href="bittorrent.pdf">Introduction, slides</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="libraryBody"><div class="section" id="libtorrent">
|
||||
<h1>libtorrent</h1>
|
||||
<p>libtorrent is a C++ library that aims to be a good alternative to all the
|
||||
other bittorrent implementations around. It is a
|
||||
library and not a full featured client, although it comes with a working
|
||||
<a class="reference" href="client_test.html">example client</a>.</p>
|
||||
<p>libtorrent is a feature complete C++ bittorrent implementation focusing
|
||||
on efficiency and scalability. It runs on embedded devices as well as
|
||||
desktops. It boasts a well documented library interface that is easy to
|
||||
use. It comes with a <a class="reference external" href="client_test.html">simple bittorrent client</a> demonstrating the use of
|
||||
the library.</p>
|
||||
<p>The main goals of libtorrent are:</p>
|
||||
<ul class="simple">
|
||||
<li>to be cpu efficient</li>
|
||||
|
|
@ -94,16 +95,28 @@ library and not a full featured client, although it comes with a working
|
|||
</form></div>
|
||||
<div class="section" id="feedback">
|
||||
<h2>Feedback</h2>
|
||||
<p>There's a <a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a>, general libtorrent discussion.</p>
|
||||
<p>There's a <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a>, general libtorrent discussion.</p>
|
||||
<p>You can usually find me as hydri in <tt class="docutils literal"><span class="pre">#libtorrent</span></tt> on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="license">
|
||||
<h2>license</h2>
|
||||
<p>libtorrent is released under the <a class="reference external" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
|
||||
<p>This means that you can use the library in your project without having to
|
||||
release its source code. The only requirement is that you give credit
|
||||
to the author of the library by including the libtorrent license in your
|
||||
software or documentation.</p>
|
||||
<p>It is however greatly appreciated if additional features are contributed
|
||||
back to the open source project. Patches can be emailed to the mailing
|
||||
list or posted to the <a class="reference external" href="http://code.rasterbar.com/libtorrent/newticket">bug tracker</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="acknowledgements">
|
||||
<h2>Acknowledgements</h2>
|
||||
<p>Written by Arvid Norberg. Copyright (c) 2003-2006</p>
|
||||
<p>Written by Arvid Norberg. Copyright © 2003-2009</p>
|
||||
<p>Contributions by 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 sourceforge.</p>
|
||||
<p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
|
||||
<p><a class="reference external" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
|
||||
</div></div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -73,10 +73,11 @@ libtorrent
|
|||
|
||||
.. _`Introduction, slides`: bittorrent.pdf
|
||||
|
||||
libtorrent is a C++ library that aims to be a good alternative to all the
|
||||
other bittorrent implementations around. It is a
|
||||
library and not a full featured client, although it comes with a working
|
||||
`example client`__.
|
||||
libtorrent is a feature complete C++ bittorrent implementation focusing
|
||||
on efficiency and scalability. It runs on embedded devices as well as
|
||||
desktops. It boasts a well documented library interface that is easy to
|
||||
use. It comes with a `simple bittorrent client`__ demonstrating the use of
|
||||
the library.
|
||||
|
||||
__ client_test.html
|
||||
|
||||
|
|
@ -116,23 +117,46 @@ __ http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss
|
|||
|
||||
You can usually find me as hydri in ``#libtorrent`` on ``irc.freenode.net``.
|
||||
|
||||
license
|
||||
=======
|
||||
|
||||
libtorrent is released under the BSD-license_.
|
||||
|
||||
.. _BSD-license: http://www.opensource.org/licenses/bsd-license.php
|
||||
|
||||
This means that you can use the library in your project without having to
|
||||
release its source code. The only requirement is that you give credit
|
||||
to the author of the library by including the libtorrent license in your
|
||||
software or documentation.
|
||||
|
||||
It is however greatly appreciated if additional features are contributed
|
||||
back to the open source project. Patches can be emailed to the mailing
|
||||
list or posted to the `bug tracker`_.
|
||||
|
||||
.. _`bug tracker`: http://code.rasterbar.com/libtorrent/newticket
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
|
||||
Written by Arvid Norberg. Copyright (c) 2003-2006
|
||||
Written by Arvid Norberg. Copyright |copy| 2003-2009
|
||||
|
||||
Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson
|
||||
|
||||
Thanks to Reimond Retz for bugfixes, suggestions and testing
|
||||
|
||||
Thanks to `Umeå University`__ for providing development and test hardware.
|
||||
|
||||
__ http://www.cs.umu.se
|
||||
|
||||
Project is hosted by sourceforge.
|
||||
|
||||
|sf_logo|__
|
||||
|
||||
.. |sf_logo| image:: http://sourceforge.net/sflogo.php?group_id=7994
|
||||
__ http://sourceforge.net
|
||||
|
||||
.. |sf_logo| image:: http://sourceforge.net/sflogo.php?group_id=7994
|
||||
.. |copy| unicode:: 0xA9 .. copyright sign
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -15,11 +15,14 @@ TARGETS = index \
|
|||
dht_extensions \
|
||||
libtorrent_plugins \
|
||||
python_binding \
|
||||
projects
|
||||
projects \
|
||||
running_tests
|
||||
|
||||
html: $(TARGETS:=.html)
|
||||
FIGURES = read_disk_buffers write_disk_buffers
|
||||
|
||||
pdf: $(TARGETS:=.pdf)
|
||||
html: $(TARGETS:=.html) $(FIGURES:=.png)
|
||||
|
||||
pdf: $(TARGETS:=.pdf) $(FIGURES:=.eps)
|
||||
|
||||
all: html
|
||||
|
||||
|
|
@ -30,6 +33,14 @@ all: html
|
|||
python $(DOCUTILS)/tools/rst2html.py --template=template.txt --stylesheet-path=style.css --link-stylesheet --no-toc-backlinks $? > $@
|
||||
cp $@ $(WEB_PATH)/$@
|
||||
|
||||
%.png:%.dot
|
||||
dot -Tpng $? >$@
|
||||
cp $@ $(WEB_PATH)/$@
|
||||
|
||||
%.eps:%.dot
|
||||
dot -Teps $? >$@
|
||||
cp $@ $(WEB_PATH)/$@
|
||||
|
||||
clean:
|
||||
rm -f $(TARGETS:=.html) $(TARGETS:=.pdf)
|
||||
|
||||
|
|
|
|||
782
docs/manual.html
782
docs/manual.html
File diff suppressed because it is too large
Load Diff
|
|
@ -75,17 +75,20 @@ The ``session`` class has the following synopsis::
|
|||
session(fingerprint const& print
|
||||
= libtorrent::fingerprint(
|
||||
"LT", 0, 1, 0, 0)
|
||||
, int flags = start_default_features | add_default_plugins
|
||||
, int flags = start_default_features
|
||||
| add_default_plugins
|
||||
, int alert_mask = alert::error_notification);
|
||||
|
||||
session(
|
||||
fingerprint const& print
|
||||
, std::pair<int, int> listen_port_range
|
||||
, char const* listen_interface = 0
|
||||
, int flags = start_default_features | add_default_plugins
|
||||
, int flags = start_default_features
|
||||
| add_default_plugins
|
||||
, int alert_mask = alert::error_notification);
|
||||
|
||||
torrent_handle add_torrent(add_torrent_params const& params);
|
||||
torrent_handle add_torrent(
|
||||
add_torrent_params const& params);
|
||||
|
||||
void pause();
|
||||
void resume();
|
||||
|
|
@ -105,7 +108,8 @@ The ``session`` class has the following synopsis::
|
|||
start_default_features = 2
|
||||
};
|
||||
|
||||
void remove_torrent(torrent_handle const& h, int options = none);
|
||||
void remove_torrent(torrent_handle const& h
|
||||
, int options = none);
|
||||
torrent_handle find_torrent(sha_hash const& ih);
|
||||
std::vector<torrent_handle> get_torrents() const;
|
||||
|
||||
|
|
@ -156,7 +160,8 @@ The ``session`` class has the following synopsis::
|
|||
std::auto_ptr<alert> pop_alert();
|
||||
alert const* wait_for_alert(time_duration max_wait);
|
||||
void set_alert_mask(int m);
|
||||
size_t set_alert_queue_size_limit(size_t queue_size_limit_);
|
||||
size_t set_alert_queue_size_limit(
|
||||
size_t queue_size_limit_);
|
||||
|
||||
void add_extension(boost::function<
|
||||
boost::shared_ptr<torrent_plugin>(torrent*)> ext);
|
||||
|
|
@ -191,13 +196,15 @@ session()
|
|||
|
||||
session(fingerprint const& print
|
||||
= libtorrent::fingerprint("LT", 0, 1, 0, 0)
|
||||
, int flags = start_default_features | add_default_plugins
|
||||
, int flags = start_default_features
|
||||
| add_default_plugins
|
||||
, int alert_mask = alert::error_notification);
|
||||
|
||||
session(fingerprint const& print
|
||||
, std::pair<int, int> listen_port_range
|
||||
, char const* listen_interface = 0
|
||||
, int flags = start_default_features | add_default_plugins
|
||||
, int flags = start_default_features
|
||||
| add_default_plugins
|
||||
, int alert_mask = alert::error_notification);
|
||||
|
||||
If the fingerprint in the first overload is omited, the client will get a default
|
||||
|
|
@ -5664,29 +5671,3 @@ for example. For more information, see the `Boost.Filesystem docs`__.
|
|||
|
||||
__ http://www.boost.org/libs/filesystem/doc/index.htm
|
||||
|
||||
|
||||
acknowledgments
|
||||
===============
|
||||
|
||||
Written by Arvid Norberg. Copyright |copy| 2003-2008
|
||||
|
||||
Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson
|
||||
|
||||
Lots of testing, suggestions and contributions by Massaroddel and Tianhao Qiu.
|
||||
|
||||
Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
|
||||
scripts.
|
||||
|
||||
Thanks to Reimond Retz for bugfixes, suggestions and testing
|
||||
|
||||
Thanks to `University of Umeå`__ for providing development and test hardware.
|
||||
|
||||
Project is hosted by sourceforge.
|
||||
|
||||
.. raw: html
|
||||
|
||||
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=7994"/></a>
|
||||
|
||||
.. |copy| unicode:: 0xA9 .. copyright sign
|
||||
__ http://www.cs.umu.se
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,20 @@
|
|||
digraph uploading {
|
||||
|
||||
node [shape=box];
|
||||
|
||||
subgraph user_space {
|
||||
rank=same;
|
||||
"disk cache" -> "send buffer" [label="copy into peer's send buffer (copy)"]
|
||||
"send buffer" -> "encrypted send buffer" [label="encrypt in-place (no copy)" style=dashed];
|
||||
}
|
||||
|
||||
subgraph kernel {
|
||||
rank=same;
|
||||
"kernel page cache";
|
||||
"socket kernel buffer"
|
||||
}
|
||||
|
||||
"encrypted send buffer" -> "socket kernel buffer" [label="write() to socket (copy)"];
|
||||
"kernel page cache" -> "disk cache" [label="read() from file (copy)"]
|
||||
}
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 5.0 KiB |
|
|
@ -3,13 +3,33 @@
|
|||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<title>libtorrent manual</title>
|
||||
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
||||
<link rel="stylesheet" type="text/css" href="../../css/base.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../../css/rst.css" />
|
||||
<link rel="stylesheet" href="style.css" type="text/css" />
|
||||
<style type="text/css">
|
||||
/* Hides from IE-mac \*/
|
||||
* html pre { height: 1%; }
|
||||
/* End hide from IE-mac */
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="document" id="libtorrent-manual">
|
||||
<div id="container">
|
||||
<div id="headerNav">
|
||||
<ul>
|
||||
<li class="first"><a href="/">Home</a></li>
|
||||
<li><a href="../../products.html">Products</a></li>
|
||||
<li><a href="../../contact.html">Contact</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="header">
|
||||
<h1><span>Rasterbar Software</span></h1>
|
||||
<h2><span>Software developement and consulting</span></h2>
|
||||
</div>
|
||||
<div id="main">
|
||||
<h1 class="title">libtorrent manual</h1>
|
||||
<table class="docinfo" frame="void" rules="none">
|
||||
<col class="docinfo-name" />
|
||||
|
|
@ -78,6 +98,17 @@ confiuration file.</p>
|
|||
<p>OpenSSL comes installed with most Linux and BSD distros, including Mac OS X.
|
||||
You can download it from <a class="reference external" href="http://www.openssl.org/">the openssl homepage</a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footer">
|
||||
<span>Copyright © 2005 Rasterbar Software.</span>
|
||||
</div>
|
||||
</div>
|
||||
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
|
||||
</script>
|
||||
<script type="text/javascript">
|
||||
_uacct = "UA-1599045-1";
|
||||
urchinTracker();
|
||||
</script>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,20 @@
|
|||
digraph downloading {
|
||||
label=""
|
||||
node [shape=box];
|
||||
|
||||
subgraph user_space {
|
||||
rank=same;
|
||||
"receive buffer" -> "plain text buffer" [label="decrypt in-place (no copy)" style=dashed];
|
||||
"plain text buffer" -> "disk cache" [label="move buffer reference (no copy)" style=dashed]
|
||||
}
|
||||
|
||||
subgraph kernel {
|
||||
rank=same;
|
||||
"socket kernel buffer";
|
||||
"kernel page cache"
|
||||
}
|
||||
|
||||
"socket kernel buffer" -> "receive buffer" [label="read() on socket (copy)"];
|
||||
"disk cache" -> "kernel page cache" [label="write() to file (copy)"]
|
||||
}
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 5.0 KiB |
Loading…
Reference in New Issue