jiigen666/libtorrent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
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
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
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 = \
{
"queuing_": "manual.html#queuing",
@@ -120,6 +126,7 @@ def is_visible(desc):
def highlight_signature(s):
name = s.split('(')
name2 = name[0].split(' ')
if len(name2[-1]) == 0: return s
name2[-1] = '**' + name2[-1] + '** '
name[0] = ' '.join(name2)
return '('.join(name)
@@ -495,7 +502,7 @@ for filename in files:
continue
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(';'):
current_class, lno = parse_class(lno -1, lines, filename)
if current_class != None and is_visible(context):
@@ -638,15 +645,28 @@ def print_declared_in(out, o):
# returns RST marked up string
def linkify_symbols(string):
lines = string.split('\n')
abort = False
ret = []
in_literal = False
for l in lines:
if l.endswith('::'):
abort = True
if abort:
if l.startswith('|'):
ret.append(l)
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(' ')
if len(words) == 1:
ret.append(l)
continue
for i in range(len(words)):
# it's important to preserve leading
# tabs, since that's relevant for
@@ -658,18 +678,24 @@ def linkify_symbols(string):
# preserve commas and dots at the end
w = words[i].strip()
trailing = ''
if len(w) == 0: continue
if (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:-1] != '()')):
trailing = w[-1]
while len(w) > 1 and (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:] != '()')):
trailing = w[-1] + trailing
w = w[:-1]
link_name = w;
# print w
if len(w) == 0: continue
if link_name[-1] == '_': link_name = link_name[:-1]
if w in symbols:
link_name = link_name.replace('-', ' ')
# print ' found %s -> %s' % (w, link_name)
words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing
ret.append(' '.join(words))
return '\n'.join(ret)
@@ -879,3 +905,19 @@ for cat in categories:
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_
* `building libtorrent`_
* examples_
* `api documentation`_
* `library overview`_
* `reference documentation`_
* `create torrents`_
* `running tests`_
* `tuning`_
@@ -58,7 +59,8 @@ libtorrent
.. _contributing: contributing.html
.. _`building libtorrent`: building.html
.. _examples: examples.html
.. _`api documentation`: manual.html
.. _`library overview`: manual-ref.html
.. _`reference documentation`: reference.html
.. _`create torrents`: make_torrent.html
.. _`running tests`: running_tests.html
.. _`tuning`: tuning.html

6
docs/makefile
View File

@@ -17,14 +17,14 @@ REFERENCE_TARGETS = \
reference-Alerts \
reference-RSS \
reference-Filter \
reference-Settings
reference-Settings \
manual-ref
TARGETS = index \
udp_tracker_protocol \
dht_rss \
dht_store \
client_test \
manual \
building \
features \
contributing\
@@ -55,7 +55,7 @@ all: html
todo.html:gen_todo.py ../src/*.cpp ../include/libtorrent/*.hpp
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
%.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:
* construct a session
* load session state from settings file (see `load_state() save_state()`_)
* 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_lsd() stop_lsd()`_, `start_upnp() stop_upnp()`_ and `start_natpmp() stop_natpmp()`_)
* parse .torrent-files and add them to the session (see `bdecode() bencode()`_ and `async_add_torrent() add_torrent()`_)
* main loop (see session_)
* load session state from settings file (see load_state())
* start extensions (see add_extension()).
* start DHT, LSD, UPnP, NAT-PMP etc (see start_dht(), start_lsd(), start_upnp() and start_natpmp()).
* parse .torrent-files and add them to the session (see torrent_info, async_add_torrent() and add_torrent())
* main loop (see session)
* query the torrent_handles for progress (see torrent_handle_)
* query the session for information
* add and remove torrents from the session at run-time
* poll for alerts (see wait_for_alert(), pop_alerts())
* handle updates to torrents, (see state_update_alert).
* 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()`_)
* save session state (see `load_state() save_state()`_)
save_resume_data())
* save session state (see save_state())
* destruct session object
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
@@ -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
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
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.
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)``.
readv() writev()
----------------
::
@@ -479,7 +479,7 @@ download, without any .torrent file.
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
=======
@@ -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
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
``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
more non-auto managed torrents being downloaded than the ``active_downloads``
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
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.
See `save_resume_data()`_.
See save_resume_data().
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.
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
-------
@@ -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).
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
@@ -544,14 +544,14 @@ fast resume
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
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
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
blocks, in the unfinished pieces, were downloaded, so it will not have to
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
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.
@@ -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.
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
any files have priority 0 and if the filesystem supports sparse files.
@@ -839,12 +839,12 @@ allocating a new slot:
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,
and the payload is the data in the extended message (not counting the
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
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
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
picker mode is determined by ``session_settings::initial_picker_threshold``.
picker mode is determined by session_settings::initial_picker_threshold.
reverse order
-------------
@@ -1043,7 +1043,7 @@ parole mode
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
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
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
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
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
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
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 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
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,
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
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.
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
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.

11
include/libtorrent/bencode.hpp
View File

@@ -413,20 +413,18 @@ namespace libtorrent
// Or, if you have a raw char buffer::
//
// const char* buf;
// ...
// // ...
// entry e = bdecode(buf, buf + data_size);
//
// 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
// it will throw libtorrent_exception.
template<class OutIt>
int bencode(OutIt out, const entry& e)
TORRENT_EXPORT template<class OutIt> int bencode(OutIt out, const entry& e)
{
return detail::bencode_recursive(out, e);
}
template<class InIt>
entry bdecode(InIt start, InIt end)
TORRENT_EXPORT template<class InIt> entry bdecode(InIt start, InIt end)
{
entry e;
bool err = false;
@@ -437,8 +435,7 @@ namespace libtorrent
if (err) return entry();
return e;
}
template<class InIt>
entry bdecode(InIt start, InIt end, int& len)
TORRENT_EXPORT template<class InIt> entry bdecode(InIt start, InIt end, int& len)
{
entry e;
bool err = false;