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

more documentation polishing. the manual.rst is now also linked to the reference documentation

This commit is contained in:
Arvid Norberg 2013-08-11 16:57:33 +00:00
parent 6036cdcf6b
commit 000addec8a
5 changed files with 94 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
docs/gen_reference_doc.py
View File

@ -26,8 +26,14 @@ overviews = {}
# maps names -> URL # maps names -> URL
symbols = {} symbols = {}
# some pre-defined sections from the main manual # some files that need pre-processing to turn symbols into
# links into the reference documentation
preprocess_rst = \
{
'manual.rst':'manual-ref.rst',
}
# some pre-defined sections from the main manual
symbols = \ symbols = \
{ {
"queuing_": "manual.html#queuing", "queuing_": "manual.html#queuing",
@ -120,6 +126,7 @@ def is_visible(desc):
def highlight_signature(s): def highlight_signature(s):
name = s.split('(') name = s.split('(')
name2 = name[0].split(' ') name2 = name[0].split(' ')
if len(name2[-1]) == 0: return s
name2[-1] = '**' + name2[-1] + '** ' name2[-1] = '**' + name2[-1] + '** '
name[0] = ' '.join(name2) name[0] = ' '.join(name2)
return '('.join(name) return '('.join(name)
@ -495,7 +502,7 @@ for filename in files:
continue continue
if 'TORRENT_EXPORT ' in l or l.startswith('inline ') or internal: if 'TORRENT_EXPORT ' in l or l.startswith('inline ') or internal:
if 'class ' in l or 'struct ' in l: if l.startswith('class ') or l.startswith('struct '):
if not l.endswith(';'): if not l.endswith(';'):
current_class, lno = parse_class(lno -1, lines, filename) current_class, lno = parse_class(lno -1, lines, filename)
if current_class != None and is_visible(context): if current_class != None and is_visible(context):
@ -638,15 +645,28 @@ def print_declared_in(out, o):
# returns RST marked up string # returns RST marked up string
def linkify_symbols(string): def linkify_symbols(string):
lines = string.split('\n') lines = string.split('\n')
abort = False
ret = [] ret = []
in_literal = False
for l in lines: for l in lines:
if l.endswith('::'): if l.startswith('|'):
abort = True
if abort:
ret.append(l) ret.append(l)
continue continue
if in_literal and not l.startswith('\t') and not l == '':
# print ' end literal: "%s"' % l
in_literal = False
if in_literal:
# print ' literal: "%s"' % l
ret.append(l)
continue
if l.endswith('::'):
# print ' start literal: "%s"' % l
in_literal = True
words = l.split(' ') words = l.split(' ')
if len(words) == 1:
ret.append(l)
continue
for i in range(len(words)): for i in range(len(words)):
# it's important to preserve leading # it's important to preserve leading
# tabs, since that's relevant for # tabs, since that's relevant for
@ -658,18 +678,24 @@ def linkify_symbols(string):
# preserve commas and dots at the end # preserve commas and dots at the end
w = words[i].strip() w = words[i].strip()
trailing = '' trailing = ''
if len(w) == 0: continue if len(w) == 0: continue
if (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:-1] != '()')): while len(w) > 1 and (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:] != '()')):
trailing = w[-1] trailing = w[-1] + trailing
w = w[:-1] w = w[:-1]
link_name = w; link_name = w;
# print w
if len(w) == 0: continue
if link_name[-1] == '_': link_name = link_name[:-1] if link_name[-1] == '_': link_name = link_name[:-1]
if w in symbols: if w in symbols:
link_name = link_name.replace('-', ' ') link_name = link_name.replace('-', ' ')
# print ' found %s -> %s' % (w, link_name)
words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing
ret.append(' '.join(words)) ret.append(' '.join(words))
return '\n'.join(ret) return '\n'.join(ret)
@ -879,3 +905,19 @@ for cat in categories:
out.close() out.close()
#for s in symbols:
# print s
for i,o in preprocess_rst.items():
f = open(i, 'r')
out = open(o, 'w+')
print 'processing %s -> %s' % (i, o)
l = linkify_symbols(f.read())
print >>out, l,
print >>out, dump_link_targets()
out.close()
f.close()

6
docs/index.rst
View File

@ -7,7 +7,8 @@
* contributing_ * contributing_
* `building libtorrent`_ * `building libtorrent`_
* examples_ * examples_
* `api documentation`_ * `library overview`_
* `reference documentation`_
* `create torrents`_ * `create torrents`_
* `running tests`_ * `running tests`_
* `tuning`_ * `tuning`_
@ -58,7 +59,8 @@ libtorrent
.. _contributing: contributing.html .. _contributing: contributing.html
.. _`building libtorrent`: building.html .. _`building libtorrent`: building.html
.. _examples: examples.html .. _examples: examples.html
.. _`api documentation`: manual.html .. _`library overview`: manual-ref.html
.. _`reference documentation`: reference.html
.. _`create torrents`: make_torrent.html .. _`create torrents`: make_torrent.html
.. _`running tests`: running_tests.html .. _`running tests`: running_tests.html
.. _`tuning`: tuning.html .. _`tuning`: tuning.html

6
docs/makefile
View File

@ -17,14 +17,14 @@ REFERENCE_TARGETS = \
reference-Alerts \ reference-Alerts \
reference-RSS \ reference-RSS \
reference-Filter \ reference-Filter \
reference-Settings reference-Settings \
manual-ref
TARGETS = index \ TARGETS = index \
udp_tracker_protocol \ udp_tracker_protocol \
dht_rss \ dht_rss \
dht_store \ dht_store \
client_test \ client_test \
manual \
building \ building \
features \ features \
contributing\ contributing\
@ -55,7 +55,7 @@ all: html
todo.html:gen_todo.py ../src/*.cpp ../include/libtorrent/*.hpp todo.html:gen_todo.py ../src/*.cpp ../include/libtorrent/*.hpp
python gen_todo.py python gen_todo.py
$(REFERENCE_TARGETS:=.rst):gen_reference_doc.py ../include/libtorrent/*.hpp ../include/libtorrent/kademlia/*.hpp $(REFERENCE_TARGETS:=.rst):gen_reference_doc.py ../include/libtorrent/*.hpp ../include/libtorrent/kademlia/*.hpp manual.rst
python gen_reference_doc.py python gen_reference_doc.py
%.epub:%.rst %.epub:%.rst

66
docs/manual.rst
View File

@ -18,25 +18,26 @@ the ``session``, it contains the main loop that serves all torrents.
The basic usage is as follows: The basic usage is as follows:
* construct a session * construct a session
* load session state from settings file (see `load_state() save_state()`_) * load session state from settings file (see load_state())
* start extensions (see `add_extension()`_). * start extensions (see add_extension()).
* start DHT, LSD, UPnP, NAT-PMP etc (see `start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()`_ * start DHT, LSD, UPnP, NAT-PMP etc (see start_dht(), start_lsd(), start_upnp() and start_natpmp()).
`start_lsd() stop_lsd()`_, `start_upnp() stop_upnp()`_ and `start_natpmp() stop_natpmp()`_) * parse .torrent-files and add them to the session (see torrent_info, async_add_torrent() and add_torrent())
* parse .torrent-files and add them to the session (see `bdecode() bencode()`_ and `async_add_torrent() add_torrent()`_) * main loop (see session)
* main loop (see session_)
* query the torrent_handles for progress (see torrent_handle_) * poll for alerts (see wait_for_alert(), pop_alerts())
* query the session for information * handle updates to torrents, (see state_update_alert).
* add and remove torrents from the session at run-time * handle other alerts, (see alert).
* query the session for information (see session::status()).
* add and remove torrents from the session (remove_torrent())
* save resume data for all torrent_handles (optional, see * save resume data for all torrent_handles (optional, see
`save_resume_data()`_) save_resume_data())
* save session state (see `load_state() save_state()`_) * save session state (see save_state())
* destruct session object * destruct session object
Each class and function is described in this manual. Each class and function is described in this manual.
For a description on how to create torrent files, see make_torrent_. For a description on how to create torrent files, see make_torrent.
.. _make_torrent: make_torrent.html .. _make_torrent: make_torrent.html
@ -64,7 +65,7 @@ the write error is caused by a full disk or write permission errors. If the
torrent is auto-managed, it will periodically be taken out of the upload torrent is auto-managed, it will periodically be taken out of the upload
mode, trying to write things to the disk again. This means torrent will recover mode, trying to write things to the disk again. This means torrent will recover
from certain disk errors if the problem is resolved. If the torrent is not 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
@ -193,7 +194,6 @@ opportunity to hint the operating system about this coming read. For instance, t
storage may call ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``. storage may call ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
readv() writev() readv() writev()
----------------
:: ::
@ -479,7 +479,7 @@ download, without any .torrent file.
The format of the magnet URI is: The format of the magnet URI is:
**magnet:?xt=urn:btih:** *Base32 encoded info-hash* [ **&dn=** *name of download* ] [ **&tr=** *tracker URL* ]* **magnet:?xt=urn:btih:** *Base16 encoded info-hash* [ **&dn=** *name of download* ] [ **&tr=** *tracker URL* ]*
queuing queuing
======= =======
@ -490,10 +490,10 @@ downloaded, the next in line is started.
Torrents that are *auto managed* are subject to the queuing and the active torrents Torrents that are *auto managed* are subject to the queuing and the active torrents
limits. To make a torrent auto managed, set ``auto_managed`` to true when adding the limits. To make a torrent auto managed, set ``auto_managed`` to true when adding the
torrent (see `async_add_torrent() add_torrent()`_). torrent (see async_add_torrent() and add_torrent()).
The limits of the number of downloading and seeding torrents are controlled via The limits of the number of downloading and seeding torrents are controlled via
``active_downloads``, ``active_seeds`` and ``active_limit`` in session_settings_. ``active_downloads``, ``active_seeds`` and ``active_limit`` in session_settings.
These limits takes non auto managed torrents into account as well. If there are These limits takes non auto managed torrents into account as well. If there are
more non-auto managed torrents being downloaded than the ``active_downloads`` more non-auto managed torrents being downloaded than the ``active_downloads``
setting, any auto managed torrents will be queued until torrents are removed so setting, any auto managed torrents will be queued until torrents are removed so
@ -503,10 +503,10 @@ The default values are 8 active downloads and 5 active seeds.
At a regular interval, torrents are checked if there needs to be any re-ordering of At a regular interval, torrents are checked if there needs to be any re-ordering of
which torrents are active and which are queued. This interval can be controlled via which torrents are active and which are queued. This interval can be controlled via
``auto_manage_interval`` in session_settings_. It defaults to every 30 seconds. ``auto_manage_interval`` in session_settings. It defaults to every 30 seconds.
For queuing to work, resume data needs to be saved and restored for all torrents. For queuing to work, resume data needs to be saved and restored for all torrents.
See `save_resume_data()`_. See save_resume_data().
downloading downloading
----------- -----------
@ -524,7 +524,7 @@ Lower queue position means closer to the front of the queue, and will be started
torrents with higher queue positions. torrents with higher queue positions.
To query a torrent for its position in the queue, or change its position, see: To query a torrent for its position in the queue, or change its position, see:
`queue_position() queue_position_up() queue_position_down() queue_position_top() queue_position_bottom()`_. queue_position(), queue_position_up(), queue_position_down(), queue_position_top() and queue_position_bottom().
seeding seeding
------- -------
@ -536,7 +536,7 @@ seeding. A seed cycle is completed when a torrent meets either the share ratio l
downloaing) or seed time limit (time seeded). downloaing) or seed time limit (time seeded).
The relevant settings to control these limits are ``share_ratio_limit``, The relevant settings to control these limits are ``share_ratio_limit``,
``seed_time_ratio_limit`` and ``seed_time_limit`` in session_settings_. ``seed_time_ratio_limit`` and ``seed_time_limit`` in session_settings.
fast resume fast resume
@ -544,14 +544,14 @@ fast resume
The fast resume mechanism is a way to remember which pieces are downloaded The fast resume mechanism is a way to remember which pieces are downloaded
and where they are put between sessions. You can generate fast resume data by and where they are put between sessions. You can generate fast resume data by
calling `save_resume_data()`_ on torrent_handle_. You can calling save_resume_data() on torrent_handle. You can
then save this data to disk and use it when resuming the torrent. libtorrent then save this data to disk and use it when resuming the torrent. libtorrent
will not check the piece hashes then, and rely on the information given in the will not check the piece hashes then, and rely on the information given in the
fast-resume data. The fast-resume data also contains information about which fast-resume data. The fast-resume data also contains information about which
blocks, in the unfinished pieces, were downloaded, so it will not have to blocks, in the unfinished pieces, were downloaded, so it will not have to
start from scratch on the partially downloaded pieces. start from scratch on the partially downloaded pieces.
To use the fast-resume data you simply give it to `async_add_torrent() add_torrent()`_, and it To use the fast-resume data you simply give it to async_add_torrent() and add_torrent(), and it
will skip the time consuming checks. It may have to do the checking anyway, if will skip the time consuming checks. It may have to do the checking anyway, if
the fast-resume data is corrupt or doesn't fit the storage for that torrent, the fast-resume data is corrupt or doesn't fit the storage for that torrent,
then it will not trust the fast-resume data and just do the checking. then it will not trust the fast-resume data and just do the checking.
@ -730,7 +730,7 @@ Support for this is deprecated and will be removed in future versions of libtorr
It's still described in here for completeness. It's still described in here for completeness.
The allocation mode is selected when a torrent is started. It is passed as an The allocation mode is selected when a torrent is started. It is passed as an
argument to ``session::add_torrent()`` (see `async_add_torrent() add_torrent()`_). argument to session::add_torrent() or session::async_add_torrent().
The decision to use full allocation or compact allocation typically depends on whether The decision to use full allocation or compact allocation typically depends on whether
any files have priority 0 and if the filesystem supports sparse files. any files have priority 0 and if the filesystem supports sparse files.
@ -839,12 +839,12 @@ allocating a new slot:
extensions extensions
========== ==========
These extensions all operates within the `extension protocol`__. The These extensions all operates within the `extension protocol`_. The
name of the extension is the name used in the extension-list packets, name of the extension is the name used in the extension-list packets,
and the payload is the data in the extended message (not counting the and the payload is the data in the extended message (not counting the
length-prefix, message-id nor extension-id). length-prefix, message-id nor extension-id).
__ extension_protocol.html .. _`extension protocol`: extension_protocol.html
Note that since this protocol relies on one of the reserved bits in the Note that since this protocol relies on one of the reserved bits in the
handshake, it may be incompatible with future versions of the mainline handshake, it may be incompatible with future versions of the mainline
@ -1024,7 +1024,7 @@ the client from getting started into the normal tit-for-tat mode of
bittorrent, and will result in a long ramp-up time. The heuristic to bittorrent, and will result in a long ramp-up time. The heuristic to
mitigate this problem is to, for the first few pieces, pick random pieces mitigate this problem is to, for the first few pieces, pick random pieces
rather than rare pieces. The threshold for when to leave this initial rather than rare pieces. The threshold for when to leave this initial
picker mode is determined by ``session_settings::initial_picker_threshold``. picker mode is determined by session_settings::initial_picker_threshold.
reverse order reverse order
------------- -------------
@ -1043,7 +1043,7 @@ parole mode
Peers that have participated in a piece that failed the hash check, may be Peers that have participated in a piece that failed the hash check, may be
put in *parole mode*. This means we prefer downloading a full piece from this put in *parole mode*. This means we prefer downloading a full piece from this
peer, in order to distinguish which peer is sending corrupt data. Whether to peer, in order to distinguish which peer is sending corrupt data. Whether to
do this is or not is controlled by ``session_settings::use_parole_mode``. do this is or not is controlled by session_settings::use_parole_mode.
In parole mode, the piece picker prefers picking one whole piece at a time for In parole mode, the piece picker prefers picking one whole piece at a time for
a given peer, avoiding picking any blocks from a piece any other peer has a given peer, avoiding picking any blocks from a piece any other peer has
@ -1057,7 +1057,7 @@ be preferred over other pieces. The benefit of doing this is that the number of
partial pieces is minimized (and hence the turn-around time for downloading a block partial pieces is minimized (and hence the turn-around time for downloading a block
until it can be uploaded to others is minimized). It also puts less stress on the until it can be uploaded to others is minimized). It also puts less stress on the
disk cache, since fewer partial pieces need to be kept in the cache. Whether or disk cache, since fewer partial pieces need to be kept in the cache. Whether or
not to enable this is controlled by ``session_settings::prioritize_partial_pieces``. not to enable this is controlled by session_settings::prioritize_partial_pieces.
The main benefit of not prioritizing partial pieces is that the rarest first The main benefit of not prioritizing partial pieces is that the rarest first
algorithm gets to have more influence on which pieces are picked. The picker is algorithm gets to have more influence on which pieces are picked. The picker is
@ -1083,7 +1083,7 @@ threshold. The main advantage is that these peers will better utilize the
other peer's disk cache, by requesting all blocks in a single piece, from other peer's disk cache, by requesting all blocks in a single piece, from
the same peer. the same peer.
This threshold is controlled by ``session_settings::whole_pieces_threshold``. This threshold is controlled by session_settings::whole_pieces_threshold.
*TODO: piece affinity by speed category* *TODO: piece affinity by speed category*
*TODO: piece priorities* *TODO: piece priorities*
@ -1111,9 +1111,9 @@ certificates are expected to be privided to peers through some other means than
bittorrent. Typically by a peer generating a certificate request which is sent to bittorrent. Typically by a peer generating a certificate request which is sent to
the publisher of the torrent, and the publisher returning a signed certificate. the publisher of the torrent, and the publisher returning a signed certificate.
In libtorrent, `set_ssl_certificate()`_ in torrent_handle_ is used to tell libtorrent where In libtorrent, set_ssl_certificate() in torrent_handle is used to tell libtorrent where
to find the peer certificate and the private key for it. When an SSL torrent is loaded, to find the peer certificate and the private key for it. When an SSL torrent is loaded,
the torrent_need_cert_alert_ is posted to remind the user to provide a certificate. the torrent_need_cert_alert is posted to remind the user to provide a certificate.
A peer connecting to an SSL torrent MUST provide the *SNI* TLS extension (server name A peer connecting to an SSL torrent MUST provide the *SNI* TLS extension (server name
indication). The server name is the hex encoded info-hash of the torrent to connect to. indication). The server name is the hex encoded info-hash of the torrent to connect to.
@ -1121,7 +1121,7 @@ This is required for the client accepting the connection to know which certifica
present. present.
SSL connections are accepted on a separate socket from normal bittorrent connections. To SSL connections are accepted on a separate socket from normal bittorrent connections. To
pick which port the SSL socket should bind to, set ``session_settings::ssl_listen`` to a pick which port the SSL socket should bind to, set session_settings::ssl_listen to a
different port. It defaults to port 4433. This setting is only taken into account when the different port. It defaults to port 4433. This setting is only taken into account when the
normal listen socket is opened (i.e. just changing this setting won't necessarily close normal listen socket is opened (i.e. just changing this setting won't necessarily close
and re-open the SSL socket). To not listen on an SSL socket at all, set ``ssl_listen`` to 0. and re-open the SSL socket). To not listen on an SSL socket at all, set ``ssl_listen`` to 0.

11
include/libtorrent/bencode.hpp
View File

@ -413,20 +413,18 @@ namespace libtorrent
// Or, if you have a raw char buffer:: // Or, if you have a raw char buffer::
// //
// const char* buf; // const char* buf;
// ... // // ...
// entry e = bdecode(buf, buf + data_size); // entry e = bdecode(buf, buf + data_size);
// //
// Now we just need to know how to retrieve information from the entry. // Now we just need to know how to retrieve information from the entry.
// //
// If ``bdecode()`` encounters invalid encoded data in the range given to it // If ``bdecode()`` encounters invalid encoded data in the range given to it
// it will throw libtorrent_exception. // it will throw libtorrent_exception.
template<class OutIt> TORRENT_EXPORT template<class OutIt> int bencode(OutIt out, const entry& e)
int bencode(OutIt out, const entry& e)
{ {
return detail::bencode_recursive(out, e); return detail::bencode_recursive(out, e);
} }
template<class InIt> TORRENT_EXPORT template<class InIt> entry bdecode(InIt start, InIt end)
entry bdecode(InIt start, InIt end)
{ {
entry e; entry e;
bool err = false; bool err = false;
@ -437,8 +435,7 @@ namespace libtorrent
if (err) return entry(); if (err) return entry();
return e; return e;
} }
template<class InIt> TORRENT_EXPORT template<class InIt> entry bdecode(InIt start, InIt end, int& len)
entry bdecode(InIt start, InIt end, int& len)
{ {
entry e; entry e;
bool err = false; bool err = false;