wornvirtue
/
premiere-libtorrent
forked from premiere/premiere-libtorrent
1
0
Fork 0
Code Pull Requests Activity

documentation update

This commit is contained in:
Arvid Norberg 2009-02-09 03:48:27 +00:00
parent fe714b4b89
commit 855e6bc345
13 changed files with 871 additions and 589 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/building.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -36,19 +36,21 @@
<col class="docinfo-content" /> <col class="docinfo-content" />
<tbody valign="top"> <tbody valign="top">
<tr><th class="docinfo-name">Author:</th> <tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr> <td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.15.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference" href="#downloading-and-building" id="id9">downloading and building</a><ul> <li><a class="reference internal" 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 internal" 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 internal" 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 internal" 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 internal" 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 internal" 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="#building-openssl-for-windows" id="id15">building openssl for windows</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
@ -56,12 +58,12 @@
<div class="section" id="downloading-and-building"> <div class="section" id="downloading-and-building">
<h1>downloading and building</h1> <h1>downloading and building</h1>
<p>To acquire the latest version of libtorrent, you'll have to grab it from SVN. <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 &quot;out of the box&quot; in libtorrent are boost-build v2 <p>The build systems supported &quot;out of the box&quot; in libtorrent are boost-build v2
(BBv2) and autotools (for unix-like systems). If you still can't build after (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> 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> 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"> <div class="section" id="building-from-svn">
<h2>building from svn</h2> <h2>building from svn</h2>
<p>To build libtorrent from svn you need to check out the libtorrent sources from <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> If you downloaded a release tarball, you can skip this section.</p>
<p>To prepare the directory structure for building, follow these steps:</p> <p>To prepare the directory structure for building, follow these steps:</p>
<ul class="simple"> <ul class="simple">
<li>Check out libtorrent (<a class="reference" href="http://sourceforge.net/svn/?group_id=79942">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" href="http://sourceforge.net/cvs/?group_id=122478">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> <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> 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> <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> <h2>building with BBv2</h2>
<p>The primary reason to use boost-build is that it will automatically build the <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 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> for some details on this issue).</p>
<p>Since BBv2 will build the boost libraries for you, you need the full boost <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 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> to step 3 (assuming you also have boost build installed).</p>
<div class="section" id="step-1-download-boost"> <div class="section" id="step-1-download-boost">
<h3>Step 1: Download boost</h3> <h3>Step 1: Download boost</h3>
<p>You'll find boost <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041&amp;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&amp;package_id=8041&amp;release_id=619445">here</a>.</p>
<p>Extract the archive to some directory where you want it. For the sake of this <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 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 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 ; using darwin : 4.0 : g++-4.0 ;
</pre> </pre>
<p>Note that the spaces around the semi-colons and colons are important!</p> <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>
<div class="section" id="step-3-building-libtorrent"> <div class="section" id="step-3-building-libtorrent">
<h3>Step 3: Building libtorrent</h3> <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 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> bjam command line. This will make libtorrent link against <tt class="docutils literal"><span class="pre">librt</span></tt>.</p>
</div> </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 <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> 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 <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 <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> 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. <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> <p>Build features:</p>
<table border="1" class="docutils"> <table border="1" class="docutils">
<colgroup> <colgroup>
@ -290,10 +297,10 @@ with the libtorrent package.</li>
<tr><td><tt class="docutils literal"><span class="pre">geoip</span></tt></td> <tr><td><tt class="docutils literal"><span class="pre">geoip</span></tt></td>
<td><ul class="first last simple"> <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">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 in statically. Note that this code is under
LGPL license.</li> 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 is expected to be installed on the system and
it will be used.</li> it will be used.</li>
</ul> </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 <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 <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> 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 <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" href="http://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features">the section on builtin features</a>.</p> 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> </div>
<div class="section" id="building-with-autotools"> <div class="section" id="building-with-autotools">
@ -435,7 +442,7 @@ and boost.program_options.</p>
<h3>Step 1: Generating the build system</h3> <h3>Step 1: Generating the build system</h3>
<p>No build system is present if libtorrent is checked out from CVS - it <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, 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 <p>Execute the following commands, in the given order, to generate
the build system:</p> the build system:</p>
<pre class="literal-block"> <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 <p>If you're building in MS Visual Studio, you may have to set the compiler
options &quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in options &quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in
type&quot; and &quot;Enable Run-Time Type Info&quot; to Yes. For a detailed description type&quot; and &quot;Enable Run-Time Type Info&quot; 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>
<div class="section" id="build-configurations"> <div class="section" id="build-configurations">
<h2>build configurations</h2> <h2>build configurations</h2>

190
docs/features.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
@ -36,105 +36,190 @@
<col class="docinfo-content" /> <col class="docinfo-content" />
<tbody valign="top"> <tbody valign="top">
<tr><th class="docinfo-name">Author:</th> <tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="last reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr> <td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.15.0</td></tr>
</tbody> </tbody>
</table> </table>
<div class="contents topic" id="table-of-contents"> <div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p> <p class="topic-title first">Table of contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference" href="#introduction" id="id2">introduction</a></li> <li><a class="reference internal" href="#introduction" id="id2">introduction</a></li>
<li><a class="reference" href="#features" id="id3">features</a></li> <li><a class="reference internal" href="#features" id="id3">features</a><ul>
<li><a class="reference" href="#portability" id="id4">portability</a></li> <li><a class="reference internal" href="#extensions" id="id4">extensions</a></li>
<li><a class="reference" href="#license" id="id5">license</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> </ul>
</div> </div>
<div class="section" id="introduction"> <div class="section" id="introduction">
<h1>introduction</h1> <h1>introduction</h1>
<p>libtorrent is a C++ library that aims to be a good alternative to all the <p>libtorrent is a feature complete C++ bittorrent implementation focusing
other bittorrent implementations around. It is a on efficiency and scalability. It runs on embedded devices as well as
library and not a full featured client, although it comes with a working desktops. It boasts a well documented library interface that is easy to
example client.</p> use. It comes with a simple bittorrent client demonstrating the use of
<p>The main goals of libtorrent are:</p> the library.</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>
</div> </div>
<div class="section" id="features"> <div class="section" id="features">
<h1>features</h1> <h1>features</h1>
<p>libtorrent is still being developed, however it is stable. It is an ongoing <p>libtorrent is under active development. It is an ongoing project. Its
project (including this documentation). The current state includes the current state supports and includes the following features:</p>
following features:</p> <div class="section" id="extensions">
<h2>extensions</h2>
<ul class="simple"> <ul class="simple">
<li>trackerless torrents (using the Mainline kademlia DHT protocol) with <li>plugin interface for implementing custom bittorrent extensions
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> without having to modify libtorrent</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>supports trackerless torrents (using the Mainline kademlia DHT protocol) with
<li>NAT-PMP and UPnP support (automatic port mapping on routers that supports it)</li> 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>uses a separate disk I/O thread to not have the disk ever block on network or <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>
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>supports the uTorrent metadata transfer protocol (i.e. magnet links).</li> <li>supports the uTorrent metadata transfer protocol (i.e. magnet links).</li>
<li>supports the uTorrent peer exchange protocol (PEX).</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>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>multitracker extension support (supports both strict <a class="reference external" href="http://bittorrent.org/beps/bep_0012.html">BEP 12</a> and the
<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
uTorrent interpretation).</li> uTorrent interpretation).</li>
<li>tracker scrapes</li> <li>tracker scrapes</li>
<li>supports lt_trackers extension, to exchange trackers between peers</li> <li>supports lt_trackers extension, to exchange trackers between peers</li>
<li>supports both sparse files and compact file allocation (where pieces <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>
are kept consolidated on disk)</li> <li>supports the udp-tracker protocol. (<a class="reference external" href="http://bittorrent.org/beps/bep_0015.html">BEP 15</a>).</li>
<li>super seeding/initial seeding (<a class="reference" href="http://bittorrent.org/beps/bep_0016.html">BEP 16</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 &gt; 2 gigabytes.</li> <li>supports files &gt; 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 <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 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 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). <li>piece picking on block-level (as opposed to piece-level).
This means it can download parts of the same piece from different peers. 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 It will also prefer to download whole pieces from single peers if the
download speed is high enough from that particular peer.</li> 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>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 <li>can limit the upload and download bandwidth usage and the maximum number of
unchoked peers</li> unchoked peers</li>
<li>implements fair trade. User settable trade-ratio, must at least be 1:1, <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 but one can choose to trade 1 for 2 or any other ratio that isn't unfair
to the other party.</li> 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>possibility to limit the number of connections.</li>
<li>delays have messages if there's no other outgoing traffic to the peer, and <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 doesn't send have messages to peers that already has the piece. This saves
bandwidth.</li> 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 <li>selective downloading. The ability to select which parts of a torrent you
want to download.</li> want to download.</li>
<li>ip filter to disallow ip addresses and ip ranges from connecting and <li>ip filter to disallow ip addresses and ip ranges from connecting and
being connected</li> 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> </ul>
</div> </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"> <div class="section" id="portability">
<h1>portability</h1> <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 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> 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, network APIs on the most popular platforms. I/O completion ports on windows,
epoll on linux and kqueue on MacOS X and BSD.</p> epoll on linux and kqueue on MacOS X and BSD.</p>
<p>libtorrent has been successfully compiled and tested on:</p> <p>libtorrent has been successfully compiled and tested on:</p>
<ul class="simple"> <ul class="simple">
<li>Windows 2000 vc7.1, vc8</li> <li>Windows 2000, XP and Vista vc7.1, vc8</li>
<li>Linux x86 GCC 3.3, GCC 3.4.2</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>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> <li>Cygwin GCC 3.3.3</li>
</ul> </ul>
<p>Fails on:</p> <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>GCC 2.95.4</li>
<li>msvc6</li> <li>msvc6</li>
</ul> </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> </div>
<div id="footer"> <div id="footer">

189
docs/features.rst
View File

@ -12,75 +12,90 @@ libtorrent manual
introduction introduction
============ ============
libtorrent is a C++ library that aims to be a good alternative to all the libtorrent is a feature complete C++ bittorrent implementation focusing
other bittorrent implementations around. It is a on efficiency and scalability. It runs on embedded devices as well as
library and not a full featured client, although it comes with a working desktops. It boasts a well documented library interface that is easy to
example client. use. It comes with a simple bittorrent client demonstrating the use of
the library.
The main goals of libtorrent are:
* to be cpu efficient
* to be memory efficient
* to be very easy to use
features features
======== ========
libtorrent is still being developed, however it is stable. It is an ongoing libtorrent is under active development. It is an ongoing project. Its
project (including this documentation). The current state includes the current state supports and includes the following features:
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`_. 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 bittorrent `extension protocol`_. See extensions_. `BEP 10`_.
* supports the uTorrent metadata transfer protocol (i.e. magnet links). * supports the uTorrent metadata transfer protocol (i.e. magnet links).
* supports the uTorrent peer exchange protocol (PEX). * supports the uTorrent peer exchange protocol (PEX).
* supports local peer discovery (multicasts for peers on the same local network) * 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 * multitracker extension support (supports both strict `BEP 12`_ and the
uTorrent interpretation). uTorrent interpretation).
* tracker scrapes * tracker scrapes
* supports lt_trackers extension, to exchange trackers between peers * supports lt_trackers extension, to exchange trackers between peers
* supports both sparse files and compact file allocation (where pieces * `HTTP seeding`_, as specified in `BEP 17`_ and `BEP 19`_.
are kept consolidated on disk) * 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`_). * 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. * 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 * 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 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 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). * piece picking on block-level (as opposed to piece-level).
This means it can download parts of the same piece from different peers. 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 It will also prefer to download whole pieces from single peers if the
download speed is high enough from that particular peer. 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 * 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 * can limit the upload and download bandwidth usage and the maximum number of
unchoked peers unchoked peers
* implements fair trade. User settable trade-ratio, must at least be 1:1, * 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 but one can choose to trade 1 for 2 or any other ratio that isn't unfair
to the other party. 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. * possibility to limit the number of connections.
* delays have messages if there's no other outgoing traffic to the peer, and * 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 doesn't send have messages to peers that already has the piece. This saves
bandwidth. 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 * selective downloading. The ability to select which parts of a torrent you
want to download. want to download.
* ip filter to disallow ip addresses and ip ranges from connecting and * ip filter to disallow ip addresses and ip ranges from connecting and
being connected being connected
* private torrents (`BEP 27`_). * NAT-PMP and UPnP support (automatic port mapping on routers that supports it)
.. _`DHT extensions`: dht_extensions.html .. _`DHT extensions`: dht_extensions.html
.. _`BEP 5`: http://bittorrent.org/beps/bep_0005.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 .. _`BEP 27`: http://bittorrent.org/beps/bep_0027.html
.. _`extension protocol`: extension_protocol.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 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 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 boost libraries as well as zlib_ (shipped) and asio_ (shipped). At least version
1.34.1 of boost is required. 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 .. _zlib: http://www.zlib.org
.. _asio: http://asio.sf.net .. _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, network APIs on the most popular platforms. I/O completion ports on windows,
epoll on linux and kqueue on MacOS X and BSD. epoll on linux and kqueue on MacOS X and BSD.
libtorrent has been successfully compiled and tested on: libtorrent has been successfully compiled and tested on:
* Windows 2000 vc7.1, vc8 * Windows 2000, XP and Vista vc7.1, vc8
* Linux x86 GCC 3.3, GCC 3.4.2 * 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 * 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 * Cygwin GCC 3.3.3
Fails on: Fails on:
@ -123,23 +219,4 @@ Fails on:
* GCC 2.95.4 * GCC 2.95.4
* msvc6 * 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

73
docs/index.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title></title>
<link rel="stylesheet" type="text/css" href="../../css/base.css" /> <link rel="stylesheet" type="text/css" href="../../css/base.css" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" /> <link rel="stylesheet" type="text/css" href="../../css/rst.css" />
@ -32,47 +32,48 @@
<div id="librarySidebar"><ul class="simple"> <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 external" 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 external" href="features.html">features</a></li>
<li><a class="reference" href="building.html">building libtorrent</a></li> <li><a class="reference external" href="building.html">building libtorrent</a></li>
<li><a class="reference" href="examples.html">examples</a></li> <li><a class="reference external" href="examples.html">examples</a></li>
<li><a class="reference" href="manual.html">api documentation</a></li> <li><a class="reference external" href="manual.html">api documentation</a></li>
<li><a class="reference" href="make_torrent.html">create torrents</a></li> <li><a class="reference external" href="make_torrent.html">create torrents</a></li>
<li><a class="reference" href="running_tests.html">running tests</a></li> <li><a class="reference external" href="running_tests.html">running tests</a></li>
<li><a class="reference" href="client_test.png">screenshot</a></li> <li><a class="reference external" 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 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" href="projects.html">who's using libtorrent?</a></li> <li><a class="reference external" 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 external" 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 external" 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://code.rasterbar.com/libtorrent">wiki</a></li>
</ul> </ul>
<hr class="docutils" /> <hr class="docutils" />
<p>Extensions</p> <p>Extensions</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference" href="extension_protocol.html">extensions protocol</a></li> <li><a class="reference external" href="extension_protocol.html">extensions protocol</a></li>
<li><a class="reference" href="libtorrent_plugins.html">plugin interface</a></li> <li><a class="reference external" href="libtorrent_plugins.html">plugin interface</a></li>
<li><a class="reference" href="dht_extensions.html">DHT extensions</a></li> <li><a class="reference external" 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 external" 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 external" 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="http://home.elp.rr.com/tur/multitracker-spec.txt">multitracker</a></li>
</ul> </ul>
<hr class="docutils" /> <hr class="docutils" />
<p>Bindings</p> <p>Bindings</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference" href="http://libtorrent-ruby.rubyforge.org/">ruby bindings</a></li> <li><a class="reference external" 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="python_binding.html">python bindings</a></li>
</ul> </ul>
<hr class="docutils" /> <hr class="docutils" />
<ul class="simple"> <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> </ul>
</div> </div>
<div id="libraryBody"><div class="section" id="libtorrent"> <div id="libraryBody"><div class="section" id="libtorrent">
<h1>libtorrent</h1> <h1>libtorrent</h1>
<p>libtorrent is a C++ library that aims to be a good alternative to all the <p>libtorrent is a feature complete C++ bittorrent implementation focusing
other bittorrent implementations around. It is a on efficiency and scalability. It runs on embedded devices as well as
library and not a full featured client, although it comes with a working desktops. It boasts a well documented library interface that is easy to
<a class="reference" href="client_test.html">example client</a>.</p> 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> <p>The main goals of libtorrent are:</p>
<ul class="simple"> <ul class="simple">
<li>to be cpu efficient</li> <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> </form></div>
<div class="section" id="feedback"> <div class="section" id="feedback">
<h2>Feedback</h2> <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> <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>
<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"> <div class="section" id="acknowledgements">
<h2>Acknowledgements</h2> <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>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</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>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>
</div> </div>
</div> </div>

36
docs/index.rst
View File

@ -73,10 +73,11 @@ libtorrent
.. _`Introduction, slides`: bittorrent.pdf .. _`Introduction, slides`: bittorrent.pdf
libtorrent is a C++ library that aims to be a good alternative to all the libtorrent is a feature complete C++ bittorrent implementation focusing
other bittorrent implementations around. It is a on efficiency and scalability. It runs on embedded devices as well as
library and not a full featured client, although it comes with a working desktops. It boasts a well documented library interface that is easy to
`example client`__. use. It comes with a `simple bittorrent client`__ demonstrating the use of
the library.
__ client_test.html __ 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``. 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 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 Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson
Thanks to Reimond Retz for bugfixes, suggestions and testing 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. Project is hosted by sourceforge.
|sf_logo|__ |sf_logo|__
.. |sf_logo| image:: http://sourceforge.net/sflogo.php?group_id=7994
__ http://sourceforge.net __ http://sourceforge.net
.. |sf_logo| image:: http://sourceforge.net/sflogo.php?group_id=7994
.. |copy| unicode:: 0xA9 .. copyright sign
.. raw:: html .. raw:: html
</div> </div>

17
docs/makefile
View File

@ -15,11 +15,14 @@ TARGETS = index \
dht_extensions \ dht_extensions \
libtorrent_plugins \ libtorrent_plugins \
python_binding \ 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 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 $? > $@ python $(DOCUTILS)/tools/rst2html.py --template=template.txt --stylesheet-path=style.css --link-stylesheet --no-toc-backlinks $? > $@
cp $@ $(WEB_PATH)/$@ cp $@ $(WEB_PATH)/$@
%.png:%.dot
dot -Tpng $? >$@
cp $@ $(WEB_PATH)/$@
%.eps:%.dot
dot -Teps $? >$@
cp $@ $(WEB_PATH)/$@
clean: clean:
rm -f $(TARGETS:=.html) $(TARGETS:=.pdf) rm -f $(TARGETS:=.html) $(TARGETS:=.pdf)

782
docs/manual.html
View File

File diff suppressed because it is too large Load Diff

47
docs/manual.rst
View File

@ -75,17 +75,20 @@ The ``session`` class has the following synopsis::
session(fingerprint const& print session(fingerprint const& print
= libtorrent::fingerprint( = libtorrent::fingerprint(
"LT", 0, 1, 0, 0) "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); , int alert_mask = alert::error_notification);
session( session(
fingerprint const& print fingerprint const& print
, std::pair<int, int> listen_port_range , std::pair<int, int> listen_port_range
, char const* listen_interface = 0 , 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); , 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 pause();
void resume(); void resume();
@ -105,7 +108,8 @@ The ``session`` class has the following synopsis::
start_default_features = 2 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); torrent_handle find_torrent(sha_hash const& ih);
std::vector<torrent_handle> get_torrents() const; std::vector<torrent_handle> get_torrents() const;
@ -156,7 +160,8 @@ The ``session`` class has the following synopsis::
std::auto_ptr<alert> pop_alert(); std::auto_ptr<alert> pop_alert();
alert const* wait_for_alert(time_duration max_wait); alert const* wait_for_alert(time_duration max_wait);
void set_alert_mask(int m); 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< void add_extension(boost::function<
boost::shared_ptr<torrent_plugin>(torrent*)> ext); boost::shared_ptr<torrent_plugin>(torrent*)> ext);
@ -191,13 +196,15 @@ session()
session(fingerprint const& print session(fingerprint const& print
= libtorrent::fingerprint("LT", 0, 1, 0, 0) = 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); , int alert_mask = alert::error_notification);
session(fingerprint const& print session(fingerprint const& print
, std::pair<int, int> listen_port_range , std::pair<int, int> listen_port_range
, char const* listen_interface = 0 , 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); , int alert_mask = alert::error_notification);
If the fingerprint in the first overload is omited, the client will get a default 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 __ 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

20
docs/read_disk_buffers.dot Normal file
View File

@ -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)"]
}

BIN
docs/read_disk_buffers.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB

33
docs/running_tests.html
View File

@ -3,13 +3,33 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <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> <title>libtorrent manual</title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" /> <meta name="author" content="Arvid Norberg, arvid&#64;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" /> <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> </head>
<body> <body>
<div class="document" id="libtorrent-manual"> <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> <h1 class="title">libtorrent manual</h1>
<table class="docinfo" frame="void" rules="none"> <table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" /> <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. <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> You can download it from <a class="reference external" href="http://www.openssl.org/">the openssl homepage</a>.</p>
</div> </div>
</div>
<div id="footer">
<span>Copyright &copy; 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> </div>
</body> </body>
</html> </html>

20
docs/write_disk_buffers.dot Normal file
View File

@ -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)"]
}

BIN
docs/write_disk_buffers.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB