2006-08-28 02:36:00 +02:00
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
< 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" / >
2009-02-09 04:48:27 +01:00
< meta name = "generator" content = "Docutils 0.6: http://docutils.sourceforge.net/" / >
2006-08-28 02:36:00 +02:00
< title > libtorrent manual< / title >
< meta name = "author" content = "Arvid Norberg, arvid@rasterbar.com" / >
2008-10-17 05:23:30 +02:00
< link rel = "stylesheet" type = "text/css" href = "../../css/base.css" / >
< link rel = "stylesheet" type = "text/css" href = "../../css/rst.css" / >
2006-08-28 02:36:00 +02:00
< link rel = "stylesheet" href = "style.css" type = "text/css" / >
2008-10-17 05:23:30 +02:00
< style type = "text/css" >
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
< / style >
2006-08-28 02:36:00 +02:00
< / head >
< body >
< div class = "document" id = "libtorrent-manual" >
2008-10-17 05:23:30 +02:00
< 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" >
2006-08-28 02:36:00 +02:00
< h1 class = "title" > libtorrent manual< / h1 >
< table class = "docinfo" frame = "void" rules = "none" >
< col class = "docinfo-name" / >
< col class = "docinfo-content" / >
< tbody valign = "top" >
< tr > < th class = "docinfo-name" > Author:< / th >
2009-02-09 04:48:27 +01:00
< 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 >
2006-08-28 02:36:00 +02:00
< / tbody >
< / table >
< div class = "contents topic" id = "table-of-contents" >
2008-10-17 05:23:30 +02:00
< p class = "topic-title first" > Table of contents< / p >
2006-08-28 02:36:00 +02:00
< ul class = "simple" >
2009-02-09 04:48:27 +01:00
< 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 >
2009-03-21 05:36:46 +01:00
< li > < a class = "reference internal" href = "#merkle-hash-tree-torrents" id = "id11" > merkle hash tree torrents< / a > < / li >
2009-02-09 04:48:27 +01:00
< / ul >
< / li >
2009-03-21 05:36:46 +01:00
< li > < a class = "reference internal" href = "#portability" id = "id12" > portability< / a > < / li >
2006-08-28 02:36:00 +02:00
< / ul >
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "introduction" >
< h1 > introduction< / h1 >
2009-02-09 04:48:27 +01:00
< 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 >
2006-08-28 02:36:00 +02:00
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "features" >
< h1 > features< / h1 >
2009-02-09 04:48:27 +01:00
< 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 >
2006-08-28 02:36:00 +02:00
< ul class = "simple" >
2009-02-09 04:48:27 +01:00
< 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 >
2009-01-13 22:49:03 +01:00
< 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 >
2009-02-09 04:48:27 +01:00
< li > multitracker extension support (supports both strict < a class = "reference external" href = "http://bittorrent.org/beps/bep_0012.html" > BEP 12< / a > and the
2009-01-13 22:49:03 +01:00
uTorrent interpretation).< / li >
< li > tracker scrapes< / li >
< li > supports lt_trackers extension, to exchange trackers between peers< / li >
2009-02-09 04:48:27 +01:00
< 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 >
2009-03-21 05:36:46 +01:00
< li > support for merkle hash tree torrents. This makes the size of torrent files
scale well with the size of the content.< / li >
2009-02-09 04:48:27 +01:00
< / 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 >
2006-09-23 23:24:28 +02:00
< li > supports files > 2 gigabytes.< / 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 >
2009-02-09 04:48:27 +01:00
< 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 >
2006-08-28 02:36:00 +02:00
< 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 >
2006-09-23 23:24:28 +02:00
< li > supports http proxies and basic proxy authentication< / li >
2009-02-09 04:48:27 +01:00
< li > supports gzipped tracker-responses< / li >
2006-08-28 02:36:00 +02:00
< 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 > 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 > selective downloading. The ability to select which parts of a torrent you
want to download.< / li >
2006-09-23 23:24:28 +02:00
< li > ip filter to disallow ip addresses and ip ranges from connecting and
being connected< / li >
2009-02-09 04:48:27 +01:00
< li > NAT-PMP and UPnP support (automatic port mapping on routers that supports it)< / li >
2006-08-28 02:36:00 +02:00
< / ul >
< / div >
2009-02-09 04:48:27 +01:00
< / 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 >
2009-03-21 05:36:46 +01:00
< div class = "section" id = "merkle-hash-tree-torrents" >
< h2 > merkle hash tree torrents< / h2 >
< p > Merkle hash tree torrents is an extension that lets a torrent file only contain the
root hash of the hash tree forming the piece hashes. The main benefit of this feature
is that regardless of how many pieces there is in a torrent, the .torrent file will
always be the same size. It will only grow with the number of files (since it still
has to contain the file names).< / p >
< p > With regular torrents, clients have to request multiple blocks for pieces, typically
from different peers, before the data can be verified against the piece hash. The
larger the pieces are, the longer it will take to download a complete piece and verify
it. Before the piece is verified, it cannot be shared with the swarm, which means the
larger piece sizes, the slower turnaround data has when it is downloaded by peers.
Since on average the data has to sit around, waiting, in client buffers before it has
been verified and can be uploaded again.< / p >
< p > Another problem with large piece sizes is that it is harder for a client to pinpoint
the malicious or buggy peer when a piece fails, and it will take longer to re-download
it and take more tries before the piece succeeds the larger the pieces are.< / p >
< p > The piece size in regular torrents is a tradeoff between the size of the .torrent file
itself and the piece size. Often, for files that are 4 GB, the piece size is 2 or 4 MB,
just to avoid making the .torrent file too big.< / p >
< p > Merkle torrents solves these problems by removing the tradeoff between .torrent size and
piece size. With merkle torrents, the piece size can be the minimum block size (16 kB),
which lets peers verify every block of data received from peers, immediately. This
gives a minimum turnaround time and completely removes the problem of identifying malicious
peers.< / p >
< / div >
2009-02-09 04:48:27 +01:00
< / div >
2008-10-17 05:23:30 +02:00
< div class = "section" id = "portability" >
< h1 > portability< / h1 >
2009-02-09 04:48:27 +01:00
< p > libtorrent runs on most major operating systems, including Windows,
MacOS X, Linux, BSD and Solaris.
2006-08-28 02:36:00 +02:00
It uses Boost.Thread, Boost.Filesystem, Boost.Date_time and various other
2009-02-09 04:48:27 +01:00
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
2009-01-13 22:49:03 +01:00
1.34.1 of boost is required.< / p >
2009-02-09 04:48:27 +01:00
< p > libtorrent uses asio, hence it will take full advantage of high performance
2006-08-28 02:36:00 +02:00
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" >
2009-02-09 04:48:27 +01:00
< 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 >
2006-08-28 02:36:00 +02:00
< li > MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0< / li >
2009-02-09 04:48:27 +01:00
< li > SunOS 5.8 GCC 3.1 and Sunpro< / li >
2006-08-28 02:36:00 +02:00
< li > Cygwin GCC 3.3.3< / li >
< / ul >
< p > Fails on:< / p >
< ul class = "simple" >
< li > GCC 2.95.4< / li >
< li > msvc6< / li >
< / ul >
< / div >
2008-10-17 05:23:30 +02:00
< / 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 >
2006-08-28 02:36:00 +02:00
< / div >
< / body >
< / html >
