diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 037a51285..a3baab9be 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -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() + + diff --git a/docs/index.rst b/docs/index.rst index 5e9aece1a..4967a9652 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/makefile b/docs/makefile index 90ac29768..5eae4ebda 100644 --- a/docs/makefile +++ b/docs/makefile @@ -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 diff --git a/docs/manual.rst b/docs/manual.rst index 351eda318..69c62959b 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -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. diff --git a/include/libtorrent/bencode.hpp b/include/libtorrent/bencode.hpp index 444beb8ce..705f4030f 100644 --- a/include/libtorrent/bencode.hpp +++ b/include/libtorrent/bencode.hpp @@ -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 - int bencode(OutIt out, const entry& e) + TORRENT_EXPORT template int bencode(OutIt out, const entry& e) { return detail::bencode_recursive(out, e); } - template - entry bdecode(InIt start, InIt end) + TORRENT_EXPORT template entry bdecode(InIt start, InIt end) { entry e; bool err = false; @@ -437,8 +435,7 @@ namespace libtorrent if (err) return entry(); return e; } - template - entry bdecode(InIt start, InIt end, int& len) + TORRENT_EXPORT template entry bdecode(InIt start, InIt end, int& len) { entry e; bool err = false;