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

add some documentation of the internals of libtorrent

This commit is contained in:
Arvid Norberg 2011-12-11 09:44:05 +00:00
parent df0d714713
commit f5d2cf0519
6 changed files with 278 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
docs/hacking.rst Normal file
View File

@ -0,0 +1,155 @@
==================
libtorrent hacking
==================
:Author: Arvid Norberg, arvid@rasterbar.com
:Version: 0.16.0
.. contents:: Table of contents
:depth: 2
:backlinks: none
terminology
===========
This section describes some of the terminology used throughout the
libtorrent source. Having a good understanding of some of these keywords
helps understanding what's going on.
A *piece* is a part of the data of a torrent that has a SHA-1 hash in
the .torrent file. Pieces are almost always a power of two in size, but not
necessarily. Each piece is plit up in *blocks*, which is a 16 kiB. A block
never spans two pieces. If a piece is smaller than 16 kiB or not divisible
by 16 kiB, there are blocks smaller than that.
16 kiB is a de-facto standard of the largest transfer unit in the bittorrent
protocol. Clients typically reject any request for larger pieces than this.
The *piece picker* is the part of a bittorrent client that is responsible for
the logic to determine which requests to send to peers. It doesn't actually
pick full pieces, but blocks (from pieces).
The file layout of a torrent is represented by *file storage* objects. This
class contains a list of all files in the torrent (in a well defined order),
the size of the pieces and implicitly the total size of the whole torrent and
number of pieces. The file storage determines the mapping from *pieces*
to *files*. This representation may be quite complex in order to keep it extremely
compact. This is useful to load very large torrents without exploding in memory
usage.
A *torrent* object represents all the state of swarm download. This includes
a piece picker, a list of peer connections, file storage (torrent file). One
important distiction is between a connected peer (*peer_connection*) and a peer
we just know about, and may have been connected to, and may connect to in the
future (*policy::peer*). The list of (not connected) peers may grow very large
if not limited (through tracker responses, DHT and peer exchange). This list
is typically limited to a few thousand peers.
The *policy* in libtorrent is somewhat poorly named. It was initially intended
to be a customization point where a client could define peer selection behavior
and unchoke logic. It didn't end up being though, and a more accurate name would
be peer_list. It really just maintains a potentially large list of known peers
for a swarm (not necessarily connected).
structure
=========
This is the high level structure of libtorrent. Bold types are part of the public
interface:
.. parsed-literal::
+=========+ pimpl +-------------------+
| **session** | ---------> | aux::session_impl |
+=========+ +-------------------+
m_torrents[] | |
+================+ | |
| **torrent_handle** | ------+ | |
+================+ | | |
| | | m_connections[]
| | |
| | +---------------------+
m_picker v v |
+--------------+ +---------+---------+-- . . |
| piece_picker | <--+-| torrent | torrent | to |
+--------------+ | +---------+---------+-- . . |
m_torrent_file | | m_connections[] |
+==============+ | | |
| **torrent_info** | <--+ v v
+==============+ | +-----------------+-----------------+-- . .
m_policy | | peer_connection | peer_connection | pe
+--------+ | +-----------------+-----------------+-- . .
| policy | <--------+ | | m_socket
+--------+ | |
| m_peers[] | v
| | +-----------------------+
| | | socket_type (variant) |
v | +-----------------------+
+--------------+ |
| policy::peer | |
+--------------+ |
| policy::peer | |
+--------------+ m_peer_info|
| policy::peer | <----------+
+--------------+
. .
+ - - - - - - -+
session_impl
------------
This is the session state object, containing all session global information, such as:
* the list of all torrents ``m_torrent``.
* the list of all peer connections ``m_connections``.
* the global rate limits ``m_settings``.
* the DHT state ``m_dht``.
* the port mapping state, ``m_upnp`` and ``m_natpmp``.
session
-------
This is the public interface to the session. It implements pimpl (pointer to implementation)
in order to hide the internal representation of the ``session_impl`` object from the user and
make binary compatibility simpler to maintain.
torrent_handle
--------------
This is the public interface to a ``torrent``. It holds a weak reference to the internal
``torrent`` object and manipulates it by sending messages to the network thread.
torrent
-------
peer_connection
---------------
policy
------
piece_picker
------------
torrent_info
------------
threads
=======
libtorrent starts 2 or 3 threads.
* The first thread is the main thread that will sit
idle in a ``kqueue()`` or ``epoll`` call most of the time.
This thread runs the main loop that will send and receive
data on all connections.
* The second thread is the disk I/O thread. All disk read and write operations
are passed to this thread and messages are passed back to the main thread when
the operation completes. The disk thread also verifies the piece hashes.
* The third and forth threads are spawned by asio on systems that don't support
non-blocking host name resolution to simulate non-blocking getaddrinfo().

27
docs/make_torrent.html
View File

@ -2,25 +2,23 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <!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"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<script type="text/javascript">
/* <![CDATA[ */
(function() {
var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
t.parentNode.insertBefore(s, t);
})();
/* ]]> */
</script>
<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.5: http://docutils.sourceforge.net/" />
<title>creating torrents</title> <title>creating torrents</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" />
<link rel="stylesheet" type="text/css" href="../../css/rst.css" /> <link rel="stylesheet" type="text/css" href="../../css/rst.css" />
<script type="text/javascript">
/* <![CDATA[ */
(function() {
var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
t.parentNode.insertBefore(s, t);
})();
/* ]]> */
</script>
<link rel="stylesheet" href="style.css" type="text/css" /> <link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css"> <style type="text/css">
/* Hides from IE-mac \*/ /* Hides from IE-mac \*/
@ -377,7 +375,8 @@ piece_size will be calculated such that the torrent file is roughly 40 kB.</p>
<p>If a <tt class="docutils literal"><span class="pre">pad_size_limit</span></tt> is specified (other than -1), any file larger than <p>If a <tt class="docutils literal"><span class="pre">pad_size_limit</span></tt> is specified (other than -1), any file larger than
the specified number of bytes will be preceeded by a pad file to align it the specified number of bytes will be preceeded by a pad file to align it
with the start of a piece. The pad_file_limit is ignored unless the with the start of a piece. The pad_file_limit is ignored unless the
<tt class="docutils literal"><span class="pre">optimize</span></tt> flag is passed.</p> <tt class="docutils literal"><span class="pre">optimize</span></tt> flag is passed. Typically it doesn't make sense to set this
any lower than 4kiB.</p>
<p>The overload that takes a <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object will make a verbatim <p>The overload that takes a <tt class="docutils literal"><span class="pre">torrent_info</span></tt> object will make a verbatim
copy of its info dictionary (to preserve the info-hash). The copy of copy of its info dictionary (to preserve the info-hash). The copy of
the info dictionary will be used by <tt class="docutils literal"><span class="pre">generate()</span></tt>. This means the info dictionary will be used by <tt class="docutils literal"><span class="pre">generate()</span></tt>. This means

3
docs/makefile
View File

@ -22,7 +22,8 @@ TARGETS = index \
projects \ projects \
running_tests \ running_tests \
utp \ utp \
tuning tuning \
hacking
FIGURES = read_disk_buffers write_disk_buffers troubleshooting FIGURES = read_disk_buffers write_disk_buffers troubleshooting

222
docs/manual.html
View File

@ -55,84 +55,85 @@
<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 internal" href="#overview" id="id14">overview</a></li> <li><a class="reference internal" href="#overview" id="id13">overview</a></li>
<li><a class="reference internal" href="#things-to-keep-in-mind" id="id15">things to keep in mind</a></li> <li><a class="reference internal" href="#things-to-keep-in-mind" id="id14">things to keep in mind</a></li>
<li><a class="reference internal" href="#network-primitives" id="id16">network primitives</a></li> <li><a class="reference internal" href="#network-primitives" id="id15">network primitives</a></li>
<li><a class="reference internal" href="#session" id="id17">session</a><ul> <li><a class="reference internal" href="#session" id="id16">session</a><ul>
<li><a class="reference internal" href="#id1" id="id18">session()</a></li> <li><a class="reference internal" href="#id1" id="id17">session()</a></li>
<li><a class="reference internal" href="#id2" id="id19">~session()</a></li> <li><a class="reference internal" href="#id2" id="id18">~session()</a></li>
<li><a class="reference internal" href="#load-state-save-state" id="id20">load_state() save_state()</a></li> <li><a class="reference internal" href="#load-state-save-state" id="id19">load_state() save_state()</a></li>
<li><a class="reference internal" href="#pause-resume-is-paused" id="id21">pause() resume() is_paused()</a></li> <li><a class="reference internal" href="#pause-resume-is-paused" id="id20">pause() resume() is_paused()</a></li>
<li><a class="reference internal" href="#abort" id="id22">abort()</a></li> <li><a class="reference internal" href="#abort" id="id21">abort()</a></li>
<li><a class="reference internal" href="#async-add-torrent-add-torrent" id="id23">async_add_torrent() add_torrent()</a></li> <li><a class="reference internal" href="#async-add-torrent-add-torrent" id="id22">async_add_torrent() add_torrent()</a></li>
<li><a class="reference internal" href="#remove-torrent" id="id24">remove_torrent()</a></li> <li><a class="reference internal" href="#remove-torrent" id="id23">remove_torrent()</a></li>
<li><a class="reference internal" href="#find-torrent-get-torrents" id="id25">find_torrent() get_torrents()</a></li> <li><a class="reference internal" href="#find-torrent-get-torrents" id="id24">find_torrent() get_torrents()</a></li>
<li><a class="reference internal" href="#get-torrent-status-refresh-torrent-status" id="id26">get_torrent_status() refresh_torrent_status()</a></li> <li><a class="reference internal" href="#get-torrent-status-refresh-torrent-status" id="id25">get_torrent_status() refresh_torrent_status()</a></li>
<li><a class="reference internal" href="#post-torrent-updates" id="id27">post_torrent_updates()</a></li> <li><a class="reference internal" href="#post-torrent-updates" id="id26">post_torrent_updates()</a></li>
<li><a class="reference internal" href="#load-asnum-db-load-country-db-as-for-ip" id="id28">load_asnum_db() load_country_db() as_for_ip()</a></li> <li><a class="reference internal" href="#load-asnum-db-load-country-db-as-for-ip" id="id27">load_asnum_db() load_country_db() as_for_ip()</a></li>
<li><a class="reference internal" href="#set-ip-filter" id="id29">set_ip_filter()</a></li> <li><a class="reference internal" href="#set-ip-filter" id="id28">set_ip_filter()</a></li>
<li><a class="reference internal" href="#get-ip-filter" id="id30">get_ip_filter()</a></li> <li><a class="reference internal" href="#get-ip-filter" id="id29">get_ip_filter()</a></li>
<li><a class="reference internal" href="#status" id="id31">status()</a></li> <li><a class="reference internal" href="#status" id="id30">status()</a></li>
<li><a class="reference internal" href="#get-cache-status" id="id32">get_cache_status()</a></li> <li><a class="reference internal" href="#get-cache-status" id="id31">get_cache_status()</a></li>
<li><a class="reference internal" href="#get-cache-info" id="id33">get_cache_info()</a></li> <li><a class="reference internal" href="#get-cache-info" id="id32">get_cache_info()</a></li>
<li><a class="reference internal" href="#is-listening-listen-port-listen-on" id="id34">is_listening() listen_port() listen_on()</a></li> <li><a class="reference internal" href="#is-listening-listen-port-listen-on" id="id33">is_listening() listen_port() listen_on()</a></li>
<li><a class="reference internal" href="#set-alert-mask" id="id35">set_alert_mask()</a></li> <li><a class="reference internal" href="#set-alert-mask" id="id34">set_alert_mask()</a></li>
<li><a class="reference internal" href="#pop-alerts-pop-alert-wait-for-alert" id="id36">pop_alerts() pop_alert() wait_for_alert()</a></li> <li><a class="reference internal" href="#pop-alerts-pop-alert-wait-for-alert" id="id35">pop_alerts() pop_alert() wait_for_alert()</a></li>
<li><a class="reference internal" href="#add-feed" id="id37">add_feed()</a></li> <li><a class="reference internal" href="#add-feed" id="id36">add_feed()</a></li>
<li><a class="reference internal" href="#remove-feed" id="id38">remove_feed()</a></li> <li><a class="reference internal" href="#remove-feed" id="id37">remove_feed()</a></li>
<li><a class="reference internal" href="#get-feeds" id="id39">get_feeds()</a></li> <li><a class="reference internal" href="#get-feeds" id="id38">get_feeds()</a></li>
<li><a class="reference internal" href="#add-extension" id="id40">add_extension()</a></li> <li><a class="reference internal" href="#add-extension" id="id39">add_extension()</a></li>
<li><a class="reference internal" href="#set-settings-set-pe-settings" id="id41">set_settings() set_pe_settings()</a></li> <li><a class="reference internal" href="#set-settings-set-pe-settings" id="id40">set_settings() set_pe_settings()</a></li>
<li><a class="reference internal" href="#set-proxy-proxy" id="id42">set_proxy() proxy()</a></li> <li><a class="reference internal" href="#set-proxy-proxy" id="id41">set_proxy() proxy()</a></li>
<li><a class="reference internal" href="#set-i2p-proxy-i2p-proxy" id="id43">set_i2p_proxy() i2p_proxy()</a></li> <li><a class="reference internal" href="#set-i2p-proxy-i2p-proxy" id="id42">set_i2p_proxy() i2p_proxy()</a></li>
<li><a class="reference internal" href="#start-dht-stop-dht-set-dht-settings-dht-state-is-dht-running" id="id44">start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()</a></li> <li><a class="reference internal" href="#start-dht-stop-dht-set-dht-settings-dht-state-is-dht-running" id="id43">start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()</a></li>
<li><a class="reference internal" href="#add-dht-node-add-dht-router" id="id45">add_dht_node() add_dht_router()</a></li> <li><a class="reference internal" href="#add-dht-node-add-dht-router" id="id44">add_dht_node() add_dht_router()</a></li>
<li><a class="reference internal" href="#start-lsd-stop-lsd" id="id46">start_lsd() stop_lsd()</a></li> <li><a class="reference internal" href="#start-lsd-stop-lsd" id="id45">start_lsd() stop_lsd()</a></li>
<li><a class="reference internal" href="#start-upnp-stop-upnp" id="id47">start_upnp() stop_upnp()</a></li> <li><a class="reference internal" href="#start-upnp-stop-upnp" id="id46">start_upnp() stop_upnp()</a></li>
<li><a class="reference internal" href="#start-natpmp-stop-natpmp" id="id48">start_natpmp() stop_natpmp()</a></li> <li><a class="reference internal" href="#start-natpmp-stop-natpmp" id="id47">start_natpmp() stop_natpmp()</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#entry" id="id49">entry</a><ul> <li><a class="reference internal" href="#entry" id="id48">entry</a><ul>
<li><a class="reference internal" href="#integer-string-list-dict-type" id="id50">integer() string() list() dict() type()</a></li> <li><a class="reference internal" href="#integer-string-list-dict-type" id="id49">integer() string() list() dict() type()</a></li>
<li><a class="reference internal" href="#operator" id="id51">operator[]</a></li> <li><a class="reference internal" href="#operator" id="id50">operator[]</a></li>
<li><a class="reference internal" href="#find-key" id="id52">find_key()</a></li> <li><a class="reference internal" href="#find-key" id="id51">find_key()</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#torrent-info" id="id53">torrent_info</a><ul> <li><a class="reference internal" href="#torrent-info" id="id52">torrent_info</a><ul>
<li><a class="reference internal" href="#id3" id="id54">torrent_info()</a></li> <li><a class="reference internal" href="#id3" id="id53">torrent_info()</a></li>
<li><a class="reference internal" href="#add-tracker" id="id55">add_tracker()</a></li> <li><a class="reference internal" href="#add-tracker" id="id54">add_tracker()</a></li>
<li><a class="reference internal" href="#files-orig-files" id="id56">files() orig_files()</a></li> <li><a class="reference internal" href="#files-orig-files" id="id55">files() orig_files()</a></li>
<li><a class="reference internal" href="#remap-files" id="id57">remap_files()</a></li> <li><a class="reference internal" href="#remap-files" id="id56">remap_files()</a></li>
<li><a class="reference internal" href="#rename-file" id="id58">rename_file()</a></li> <li><a class="reference internal" href="#rename-file" id="id57">rename_file()</a></li>
<li><a class="reference internal" href="#begin-files-end-files-rbegin-files-rend-files" id="id59">begin_files() end_files() rbegin_files() rend_files()</a></li> <li><a class="reference internal" href="#begin-files-end-files-rbegin-files-rend-files" id="id58">begin_files() end_files() rbegin_files() rend_files()</a></li>
<li><a class="reference internal" href="#num-files-file-at" id="id60">num_files() file_at()</a></li> <li><a class="reference internal" href="#num-files-file-at" id="id59">num_files() file_at()</a></li>
<li><a class="reference internal" href="#map-block" id="id61">map_block()</a></li> <li><a class="reference internal" href="#map-block" id="id60">map_block()</a></li>
<li><a class="reference internal" href="#map-file" id="id62">map_file()</a></li> <li><a class="reference internal" href="#map-file" id="id61">map_file()</a></li>
<li><a class="reference internal" href="#add-url-seed-add-http-seed" id="id63">add_url_seed() add_http_seed()</a></li> <li><a class="reference internal" href="#add-url-seed-add-http-seed" id="id62">add_url_seed() add_http_seed()</a></li>
<li><a class="reference internal" href="#trackers" id="id64">trackers()</a></li> <li><a class="reference internal" href="#trackers" id="id63">trackers()</a></li>
<li><a class="reference internal" href="#total-size-piece-length-piece-size-num-pieces" id="id65">total_size() piece_length() piece_size() num_pieces()</a></li> <li><a class="reference internal" href="#total-size-piece-length-piece-size-num-pieces" id="id64">total_size() piece_length() piece_size() num_pieces()</a></li>
<li><a class="reference internal" href="#hash-for-piece-hash-for-piece-ptr-info-hash" id="id66">hash_for_piece() hash_for_piece_ptr() info_hash()</a></li> <li><a class="reference internal" href="#hash-for-piece-hash-for-piece-ptr-info-hash" id="id65">hash_for_piece() hash_for_piece_ptr() info_hash()</a></li>
<li><a class="reference internal" href="#merkle-tree-set-merkle-tree" id="id67">merkle_tree() set_merkle_tree()</a></li> <li><a class="reference internal" href="#merkle-tree-set-merkle-tree" id="id66">merkle_tree() set_merkle_tree()</a></li>
<li><a class="reference internal" href="#name-comment-creation-date-creator" id="id68">name() comment() creation_date() creator()</a></li> <li><a class="reference internal" href="#name-comment-creation-date-creator" id="id67">name() comment() creation_date() creator()</a></li>
<li><a class="reference internal" href="#priv" id="id69">priv()</a></li> <li><a class="reference internal" href="#priv" id="id68">priv()</a></li>
<li><a class="reference internal" href="#nodes" id="id70">nodes()</a></li> <li><a class="reference internal" href="#nodes" id="id69">nodes()</a></li>
<li><a class="reference internal" href="#add-node" id="id71">add_node()</a></li> <li><a class="reference internal" href="#add-node" id="id70">add_node()</a></li>
<li><a class="reference internal" href="#metadata-metadata-size" id="id72">metadata() metadata_size()</a></li> <li><a class="reference internal" href="#metadata-metadata-size" id="id71">metadata() metadata_size()</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#torrent-handle" id="id73">torrent_handle</a><ul> <li><a class="reference internal" href="#torrent-handle" id="id72">torrent_handle</a><ul>
<li><a class="reference internal" href="#set-piece-deadline-reset-piece-deadline" id="id74">set_piece_deadline() reset_piece_deadline()</a></li> <li><a class="reference internal" href="#set-piece-deadline-reset-piece-deadline" id="id73">set_piece_deadline() reset_piece_deadline()</a></li>
<li><a class="reference internal" href="#piece-availability" id="id75">piece_availability()</a></li> <li><a class="reference internal" href="#piece-availability" id="id74">piece_availability()</a></li>
<li><a class="reference internal" href="#piece-priority-prioritize-pieces-piece-priorities" id="id76">piece_priority() prioritize_pieces() piece_priorities()</a></li> <li><a class="reference internal" href="#piece-priority-prioritize-pieces-piece-priorities" id="id75">piece_priority() prioritize_pieces() piece_priorities()</a></li>
<li><a class="reference internal" href="#file-priority-prioritize-files-file-priorities" id="id77">file_priority() prioritize_files() file_priorities()</a></li> <li><a class="reference internal" href="#file-priority-prioritize-files-file-priorities" id="id76">file_priority() prioritize_files() file_priorities()</a></li>
<li><a class="reference internal" href="#file-progress" id="id78">file_progress()</a></li> <li><a class="reference internal" href="#file-progress" id="id77">file_progress()</a></li>
<li><a class="reference internal" href="#save-path" id="id79">save_path()</a></li> <li><a class="reference internal" href="#save-path" id="id78">save_path()</a></li>
<li><a class="reference internal" href="#move-storage" id="id80">move_storage()</a></li> <li><a class="reference internal" href="#move-storage" id="id79">move_storage()</a></li>
<li><a class="reference internal" href="#id4" id="id81">rename_file()</a></li> <li><a class="reference internal" href="#id4" id="id80">rename_file()</a></li>
<li><a class="reference internal" href="#get-storage-impl" id="id82">get_storage_impl()</a></li> <li><a class="reference internal" href="#get-storage-impl" id="id81">get_storage_impl()</a></li>
<li><a class="reference internal" href="#super-seeding" id="id83">super_seeding()</a></li> <li><a class="reference internal" href="#super-seeding" id="id82">super_seeding()</a></li>
<li><a class="reference internal" href="#add-piece" id="id84">add_piece()</a></li> <li><a class="reference internal" href="#add-piece" id="id83">add_piece()</a></li>
<li><a class="reference internal" href="#read-piece" id="id85">read_piece()</a></li> <li><a class="reference internal" href="#read-piece" id="id84">read_piece()</a></li>
<li><a class="reference internal" href="#have-piece" id="id85">have_piece()</a></li>
<li><a class="reference internal" href="#force-reannounce-force-dht-announce" id="id86">force_reannounce() force_dht_announce()</a></li> <li><a class="reference internal" href="#force-reannounce-force-dht-announce" id="id86">force_reannounce() force_dht_announce()</a></li>
<li><a class="reference internal" href="#scrape-tracker" id="id87">scrape_tracker()</a></li> <li><a class="reference internal" href="#scrape-tracker" id="id87">scrape_tracker()</a></li>
<li><a class="reference internal" href="#connect-peer" id="id88">connect_peer()</a></li> <li><a class="reference internal" href="#connect-peer" id="id88">connect_peer()</a></li>
@ -319,30 +320,28 @@
<li><a class="reference internal" href="#file-format" id="id247">file format</a></li> <li><a class="reference internal" href="#file-format" id="id247">file format</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#threads" id="id248">threads</a></li> <li><a class="reference internal" href="#storage-allocation" id="id248">storage allocation</a><ul>
<li><a class="reference internal" href="#storage-allocation" id="id249">storage allocation</a><ul> <li><a class="reference internal" href="#sparse-allocation" id="id249">sparse allocation</a></li>
<li><a class="reference internal" href="#sparse-allocation" id="id250">sparse allocation</a></li> <li><a class="reference internal" href="#full-allocation" id="id250">full allocation</a></li>
<li><a class="reference internal" href="#full-allocation" id="id251">full allocation</a></li> <li><a class="reference internal" href="#compact-allocation" id="id251">compact allocation</a></li>
<li><a class="reference internal" href="#compact-allocation" id="id252">compact allocation</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#extensions" id="id253">extensions</a><ul> <li><a class="reference internal" href="#extensions" id="id252">extensions</a><ul>
<li><a class="reference internal" href="#metadata-from-peers" id="id254">metadata from peers</a></li> <li><a class="reference internal" href="#metadata-from-peers" id="id253">metadata from peers</a></li>
<li><a class="reference internal" href="#dont-have" id="id255">dont_have</a></li> <li><a class="reference internal" href="#dont-have" id="id254">dont_have</a></li>
<li><a class="reference internal" href="#http-seeding" id="id256">HTTP seeding</a></li> <li><a class="reference internal" href="#http-seeding" id="id255">HTTP seeding</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#piece-picker" id="id257">piece picker</a><ul> <li><a class="reference internal" href="#piece-picker" id="id256">piece picker</a><ul>
<li><a class="reference internal" href="#internal-representation" id="id258">internal representation</a></li> <li><a class="reference internal" href="#internal-representation" id="id257">internal representation</a></li>
<li><a class="reference internal" href="#picker-strategy" id="id259">picker strategy</a></li> <li><a class="reference internal" href="#picker-strategy" id="id258">picker strategy</a></li>
<li><a class="reference internal" href="#reverse-order" id="id260">reverse order</a></li> <li><a class="reference internal" href="#reverse-order" id="id259">reverse order</a></li>
<li><a class="reference internal" href="#parole-mode" id="id261">parole mode</a></li> <li><a class="reference internal" href="#parole-mode" id="id260">parole mode</a></li>
<li><a class="reference internal" href="#prioritize-partial-pieces" id="id262">prioritize partial pieces</a></li> <li><a class="reference internal" href="#prioritize-partial-pieces" id="id261">prioritize partial pieces</a></li>
<li><a class="reference internal" href="#prefer-whole-pieces" id="id263">prefer whole pieces</a></li> <li><a class="reference internal" href="#prefer-whole-pieces" id="id262">prefer whole pieces</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#ssl-torrents" id="id264">SSL torrents</a></li> <li><a class="reference internal" href="#ssl-torrents" id="id263">SSL torrents</a></li>
<li><a class="reference internal" href="#filename-checks" id="id265">filename checks</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="overview"> <div class="section" id="overview">
@ -2478,6 +2477,7 @@ struct torrent_handle
enum flags_t { overwrite_existing = 1 }; enum flags_t { overwrite_existing = 1 };
void add_piece(int piece, char const* data, int flags = 0) const; void add_piece(int piece, char const* data, int flags = 0) const;
void read_piece(int piece) const; void read_piece(int piece) const;
bool have_piece(int piece) const;
sha1_hash info_hash() const; sha1_hash info_hash() const;
@ -2724,6 +2724,15 @@ calling this function.</p>
<p>Note that if you read multiple pieces, the read operations are not guaranteed to <p>Note that if you read multiple pieces, the read operations are not guaranteed to
finish in the same order as you initiated them.</p> finish in the same order as you initiated them.</p>
</div> </div>
<div class="section" id="have-piece">
<h2>have_piece()</h2>
<blockquote>
<pre class="literal-block">
bool have_piece(int piece) const;
</pre>
</blockquote>
<p>Returns true if this piece has been completely downloaded, and false otherwise.</p>
</div>
<div class="section" id="force-reannounce-force-dht-announce"> <div class="section" id="force-reannounce-force-dht-announce">
<h2>force_reannounce() force_dht_announce()</h2> <h2>force_reannounce() force_dht_announce()</h2>
<blockquote> <blockquote>
@ -8670,22 +8679,6 @@ last resume data checkpoint.</td>
</table> </table>
</div> </div>
</div> </div>
<div class="section" id="threads">
<h1>threads</h1>
<p>libtorrent starts 2 or 3 threads.</p>
<blockquote>
<ul class="simple">
<li>The first thread is the main thread that will sit
idle in a <tt class="docutils literal"><span class="pre">select()</span></tt> call most of the time. This thread runs the main loop
that will send and receive data on all connections.</li>
<li>The second thread is the disk I/O thread. All disk read and write operations
are passed to this thread and messages are passed back to the main thread when
the operation completes. The disk thread also verifies the piece hashes.</li>
<li>The third and forth threads are spawned by asio on systems that don't support
non-blocking host name resolution to simulate non-blocking getaddrinfo().</li>
</ul>
</blockquote>
</div>
<div class="section" id="storage-allocation"> <div class="section" id="storage-allocation">
<h1>storage allocation</h1> <h1>storage allocation</h1>
<p>There are two modes in which storage (files on disk) are allocated in libtorrent.</p> <p>There are two modes in which storage (files on disk) are allocated in libtorrent.</p>
@ -8719,7 +8712,7 @@ as much space as has been downloaded.</p>
</div> </div>
<div class="section" id="full-allocation"> <div class="section" id="full-allocation">
<h2>full allocation</h2> <h2>full allocation</h2>
<p>When a torrent is started in full allocation mode, the disk-io thread (see <a class="reference internal" href="#threads">threads</a>) <p>When a torrent is started in full allocation mode, the disk-io thread (see <a href="#id264"><span class="problematic" id="id265">threads_</span></a>)
will make sure that the entire storage is allocated, and fill any gaps with zeros. will make sure that the entire storage is allocated, and fill any gaps with zeros.
This will be skipped if the filesystem supports sparse files or automatic zero filling. This will be skipped if the filesystem supports sparse files or automatic zero filling.
It will of course still check for existing pieces and fast resume data. The main It will of course still check for existing pieces and fast resume data. The main
@ -9108,16 +9101,11 @@ the <a class="reference internal" href="#torrent-need-cert-alert">torrent_need_c
to provide the correct certificate, each SSL torrent opens their own dedicated listen socket.</p> to provide the correct certificate, each SSL torrent opens their own dedicated listen socket.</p>
<p>This feature is only available if libtorrent is build with openssl support (<tt class="docutils literal"><span class="pre">TORRENT_USE_OPENSSL</span></tt>).</p> <p>This feature is only available if libtorrent is build with openssl support (<tt class="docutils literal"><span class="pre">TORRENT_USE_OPENSSL</span></tt>).</p>
</div> </div>
<div class="section" id="filename-checks"> <div class="system-messages section">
<h1>filename checks</h1> <h1>Docutils System Messages</h1>
<p>Boost.Filesystem will by default check all its paths to make sure they conform <div class="system-message" id="id264">
to filename requirements on many platforms. If you don't want this check, you can <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">manual.rst</tt>, line 8717); <em><a href="#id265">backlink</a></em></p>
set it to either only check for native filesystem requirements or turn it off Unknown target name: &quot;threads&quot;.</div>
altogether. You can use:</p>
<pre class="literal-block">
boost::filesystem::path::default_name_check(boost::filesystem::native);
</pre>
<p>for example. For more information, see the <a class="reference external" href="http://www.boost.org/libs/filesystem/doc/index.htm">Boost.Filesystem docs</a>.</p>
</div> </div>
</div> </div>
<div id="footer"> <div id="footer">

36
docs/manual.rst
View File

@ -67,7 +67,6 @@ from certain disk errors if the problem is resolved. If the torrent is not
auto managed, you have to call `set_upload_mode()`_ to turn auto managed, you have to call `set_upload_mode()`_ to turn
downloading back on again. downloading back on again.
network primitives network primitives
================== ==================
@ -232,8 +231,8 @@ The ``session`` class has the following synopsis::
void add_extension(boost::function< void add_extension(boost::function<
boost::shared_ptr<torrent_plugin>(torrent*)> ext); boost::shared_ptr<torrent_plugin>(torrent*)> ext);
void start_dht(); void start_dht();
void stop_dht(); void stop_dht();
void set_dht_settings( void set_dht_settings(
dht_settings const& settings); dht_settings const& settings);
@ -8675,23 +8674,6 @@ The file format is a bencoded dictionary containing the following fields:
| | last resume data checkpoint. | | | last resume data checkpoint. |
+--------------------------+--------------------------------------------------------------+ +--------------------------+--------------------------------------------------------------+
threads
=======
libtorrent starts 2 or 3 threads.
* The first thread is the main thread that will sit
idle in a ``select()`` call most of the time. This thread runs the main loop
that will send and receive data on all connections.
* The second thread is the disk I/O thread. All disk read and write operations
are passed to this thread and messages are passed back to the main thread when
the operation completes. The disk thread also verifies the piece hashes.
* The third and forth threads are spawned by asio on systems that don't support
non-blocking host name resolution to simulate non-blocking getaddrinfo().
storage allocation storage allocation
================== ==================
@ -9101,17 +9083,3 @@ to provide the correct certificate, each SSL torrent opens their own dedicated l
This feature is only available if libtorrent is build with openssl support (``TORRENT_USE_OPENSSL``). This feature is only available if libtorrent is build with openssl support (``TORRENT_USE_OPENSSL``).
filename checks
===============
Boost.Filesystem will by default check all its paths to make sure they conform
to filename requirements on many platforms. If you don't want this check, you can
set it to either only check for native filesystem requirements or turn it off
altogether. You can use::
boost::filesystem::path::default_name_check(boost::filesystem::native);
for example. For more information, see the `Boost.Filesystem docs`__.
__ http://www.boost.org/libs/filesystem/doc/index.htm

1
set_version.py
View File

@ -41,6 +41,7 @@ substitute_file('docs/contributing.rst')
substitute_file('docs/utp.rst') substitute_file('docs/utp.rst')
substitute_file('docs/make_torrent.rst') substitute_file('docs/make_torrent.rst')
substitute_file('docs/tuning.rst') substitute_file('docs/tuning.rst')
substitute_file('docs/hacking.rst')
substitute_file('Jamfile') substitute_file('Jamfile')