diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py
index 8451c541c..89c4cfe5d 100644
--- a/docs/gen_reference_doc.py
+++ b/docs/gen_reference_doc.py
@@ -62,9 +62,9 @@ anon_index = 0
category_mapping = {
'ed25519.hpp': 'ed25519',
- 'session.hpp': 'Session',
- 'add_torrent_params.hpp': 'Session',
- 'session_status.hpp': 'Session',
+ 'session.hpp': 'Core',
+ 'add_torrent_params.hpp': 'Core',
+ 'session_status.hpp': 'Core',
'error_code.hpp': 'Error Codes',
'file.hpp': 'File',
'storage.hpp': 'Custom Storage',
@@ -86,9 +86,7 @@ category_mapping = {
'bdecode.hpp': 'Bdecoding',
'entry.hpp': 'Bencoding',
'time.hpp': 'Time',
- 'escape_string.hpp': 'String',
- 'string_util.hpp': 'String',
- 'utf8.hpp': 'String',
+ 'escape_string.hpp': 'Utility',
'enum_net.hpp': 'Network',
'broadcast_socket.hpp': 'Network',
'socket.hpp': 'Network',
@@ -96,18 +94,21 @@ category_mapping = {
'rss.hpp': 'RSS',
'bitfield.hpp': 'Utility',
'sha1_hash.hpp': 'Utility',
+ 'hasher.hpp': 'Utility',
'identify_client.hpp': 'Utility',
'thread.hpp': 'Utility',
'ip_filter.hpp': 'Filter',
'session_settings.hpp': 'Settings',
'settings_pack.hpp': 'Settings',
'operations.hpp': 'Alerts',
+ 'disk_buffer_holder.hpp': 'Custom Storage',
+ 'alert_dispatcher.hpp': 'Alerts',
}
category_fun_mapping = {
'min_memory_usage()': 'Settings',
'high_performance_seed()': 'Settings',
- 'cache_status': 'Session',
+ 'cache_status': 'Core',
}
def categorize_symbol(name, filename):
@@ -841,14 +842,15 @@ def dump_link_targets(indent = ''):
return ret
def heading(string, c, indent = ''):
+ string = string.strip()
return '\n' + indent + string + '\n' + indent + (c * len(string)) + '\n'
-def render_enums(out, enums, print_declared_reference):
+def render_enums(out, enums, print_declared_reference, header_level):
for e in enums:
print >>out, '.. raw:: html\n'
print >>out, '\t' % e['name']
print >>out, ''
- print >>out, heading('enum %s' % e['name'], '.')
+ print >>out, heading('enum %s' % e['name'], header_level)
print_declared_in(out, e)
@@ -890,7 +892,6 @@ sections = \
'Create Torrents': 1,
'ed25519': 2,
- 'String': 2,
'Utility': 2,
'Storage': 2,
'Custom Storage': 2,
@@ -1022,7 +1023,7 @@ for cat in categories:
print >>out, dump_link_targets()
- render_enums(out, c['enums'], False)
+ render_enums(out, c['enums'], False, '.')
for f in c['fields']:
if f['desc'] == '': continue
@@ -1049,7 +1050,7 @@ for cat in categories:
print >>out, ''
for n in f['names']:
h += '%s ' % n
- print >>out, heading(h, '.')
+ print >>out, heading(h, '-')
print_declared_in(out, f)
block = '.. parsed-literal::\n\n'
@@ -1061,7 +1062,7 @@ for cat in categories:
print >>out, dump_link_targets()
- render_enums(out, enums, True)
+ render_enums(out, enums, True, '-')
print >>out, dump_link_targets()
diff --git a/docs/makefile b/docs/makefile
index d39b4809b..84f46bb93 100644
--- a/docs/makefile
+++ b/docs/makefile
@@ -4,9 +4,7 @@ WEB_PATH = ~/Documents/rasterbar/web/products/libtorrent
REFERENCE_TARGETS = \
reference \
- reference-Session \
reference-Core \
- reference-String \
reference-Plugins \
reference-Create_Torrents \
reference-Error_Codes \
diff --git a/docs/manual.rst b/docs/manual.rst
index 7a25d7a3e..08e543a3f 100644
--- a/docs/manual.rst
+++ b/docs/manual.rst
@@ -687,7 +687,6 @@ disk cache, by requesting all blocks in a single piece, from the same peer.
This threshold is controlled by the settings_pack::whole_pieces_threshold
setting.
-*TODO: piece affinity by speed category*
*TODO: piece priorities*
predictive piece announce
diff --git a/docs/rst.css b/docs/rst.css
index 42c112ba6..fb911fd7e 100644
--- a/docs/rst.css
+++ b/docs/rst.css
@@ -121,9 +121,9 @@ p.admonition-title {
border-bottom: solid 1px #D1DFD5
}
-h1 { font-size: 180%; }
+h1 { font-size: 200%; }
h2 { font-size: 130%; }
-h3 { font-size: 100%; }
+h3 { font-size: 100%; font-style: italic; }
h1.title { text-align: center; }
diff --git a/docs/stats_counters.rst b/docs/stats_counters.rst
index e9eed43f9..b6c6f864e 100644
--- a/docs/stats_counters.rst
+++ b/docs/stats_counters.rst
@@ -28,6 +28,8 @@ disconnected initiated by this client (``disconnected_peers``).
.. _peer.connaborted_peers:
+.. _peer.notconnected_peers:
+
.. _peer.perm_peers:
.. _peer.buffer_peers:
@@ -50,6 +52,7 @@ disconnected initiated by this client (``disconnected_peers``).
+
@@ -59,33 +62,35 @@ disconnected initiated by this client (``disconnected_peers``).
-+------------------------+---------+
-| name | type |
-+========================+=========+
-| peer.eof_peers | counter |
-+------------------------+---------+
-| peer.connreset_peers | counter |
-+------------------------+---------+
-| peer.connrefused_peers | counter |
-+------------------------+---------+
-| peer.connaborted_peers | counter |
-+------------------------+---------+
-| peer.perm_peers | counter |
-+------------------------+---------+
-| peer.buffer_peers | counter |
-+------------------------+---------+
-| peer.unreachable_peers | counter |
-+------------------------+---------+
-| peer.broken_pipe_peers | counter |
-+------------------------+---------+
-| peer.addrinuse_peers | counter |
-+------------------------+---------+
-| peer.no_access_peers | counter |
-+------------------------+---------+
-| peer.invalid_arg_peers | counter |
-+------------------------+---------+
-| peer.aborted_peers | counter |
-+------------------------+---------+
++-------------------------+---------+
+| name | type |
++=========================+=========+
+| peer.eof_peers | counter |
++-------------------------+---------+
+| peer.connreset_peers | counter |
++-------------------------+---------+
+| peer.connrefused_peers | counter |
++-------------------------+---------+
+| peer.connaborted_peers | counter |
++-------------------------+---------+
+| peer.notconnected_peers | counter |
++-------------------------+---------+
+| peer.perm_peers | counter |
++-------------------------+---------+
+| peer.buffer_peers | counter |
++-------------------------+---------+
+| peer.unreachable_peers | counter |
++-------------------------+---------+
+| peer.broken_pipe_peers | counter |
++-------------------------+---------+
+| peer.addrinuse_peers | counter |
++-------------------------+---------+
+| peer.no_access_peers | counter |
++-------------------------+---------+
+| peer.invalid_arg_peers | counter |
++-------------------------+---------+
+| peer.aborted_peers | counter |
++-------------------------+---------+
these counters break down the peer errors into more specific
diff --git a/docs/style.css b/docs/style.css
index b6e6e04b6..4e50f5399 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -12,8 +12,7 @@
body, table { font: 0.9em Verdana, sans-serif;}
h1, h2, h3 {
- font: 1.5em Georgia "Times New Roman", serif;
-/* letter-spacing: 1px; */
+ font-family: Georgia "Times New Roman", serif;
padding-bottom: 0.5em;
font-weight: bold;
}
diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp
index 0c276a108..08cb7f8e0 100644
--- a/include/libtorrent/add_torrent_params.hpp
+++ b/include/libtorrent/add_torrent_params.hpp
@@ -318,7 +318,8 @@ namespace libtorrent
storage_constructor_type storage;
// The ``userdata`` parameter is optional and will be passed on to the
- // extension constructor functions, if any (see `add_extension()`_).
+ // extension constructor functions, if any
+ // (see torrent_handle::add_extension()).
void* userdata;
// can be set to control the initial file priorities when adding a
diff --git a/include/libtorrent/bdecode.hpp b/include/libtorrent/bdecode.hpp
index f05269556..27bc90a0e 100644
--- a/include/libtorrent/bdecode.hpp
+++ b/include/libtorrent/bdecode.hpp
@@ -287,12 +287,16 @@ struct TORRENT_EXPORT bdecode_node
, boost::int64_t default_val = 0);
int list_size() const;
- // functions with the ``dict_`` prefix operates on dictionaries. Theu are
+ // Functions with the ``dict_`` prefix operates on dictionaries. They are
// only valid if ``type()`` == ``dict_t``. In case a key you're looking up
// contains a 0 byte, you cannot use the null-terminated string overloads,
- // but have to use ``std::string`` instead. ``dict_find_list`` will return
- // a valid ``bdecode_node`` if the key is found _and_ it is a list. Otherwise
+ // but have to use ``std::string`` instead. ``dict_find_list`` will return a
+ // valid ``bdecode_node`` if the key is found _and_ it is a list. Otherwise
// it will return a default-constructed bdecode_node.
+ //
+ // Functions with the ``_value`` suffix return the value of the node
+ // directly, rather than the nodes. In case the node is not found, or it has
+ // a different type, a default value is returned (which can be specified).
bdecode_node dict_find(std::string key) const;
bdecode_node dict_find(char const* key) const;
std::pair dict_at(int i) const;
@@ -312,7 +316,7 @@ struct TORRENT_EXPORT bdecode_node
boost::int64_t int_value() const;
// these functions are only valid if ``type()`` == ``string_t``. They return
- // the string values. Note that ``string_ptr()`` is _not_ null-terminated.
+ // the string values. Note that ``string_ptr()`` is *not* null-terminated.
// ``string_length()`` returns the number of bytes in the string.
std::string string_value() const;
char const* string_ptr() const;
@@ -332,9 +336,9 @@ struct TORRENT_EXPORT bdecode_node
// passing it in to bdecode().
void reserve(int tokens);
- // this buffer MUST be identical to the one originally parsed.
- // This operation is only defined on owning root nodes, i.e. the one
- // passed in to decode().
+ // this buffer *MUST* be identical to the one originally parsed. This
+ // operation is only defined on owning root nodes, i.e. the one passed in to
+ // decode().
void switch_underlying_buffer(char const* buf);
private:
@@ -375,12 +379,12 @@ TORRENT_EXPORT std::string print_entry(bdecode_node const& e
, bool single_line = false, int indent = 0);
// This function decodes/parses bdecoded data (for example a .torrent file).
-// The data structure is returned in the ``ret`` argument.
-// the buffer to parse is specified by the ``start`` of the buffer as well as
-// the ``end``, i.e. one byte past the end. If the buffer fails to parse, the
-// function returns a non-zero value and fills in ``ec`` with the error code.
-// The optional argument ``error_pos``, if set to non-null, will be set to the byte
-// offset into the buffer where the parse failure occurred.
+// The data structure is returned in the ``ret`` argument. the buffer to parse
+// is specified by the ``start`` of the buffer as well as the ``end``, i.e. one
+// byte past the end. If the buffer fails to parse, the function returns a
+// non-zero value and fills in ``ec`` with the error code. The optional
+// argument ``error_pos``, if set to non-null, will be set to the byte offset
+// into the buffer where the parse failure occurred.
//
// ``depth_limit`` specifies the max number of nested lists or dictionaries are
// allowed in the data structure. (This affects the stack usage of the
@@ -391,9 +395,9 @@ TORRENT_EXPORT std::string print_entry(bdecode_node const& e
//
// The resulting ``bdecode_node`` is an *owning* node. That means it will
// be holding the whole parsed tree. When iterating lists and dictionaries,
-// those ``bdecode_node``s will simply have references to the root or owning
-// ``bdecode_node``. If the root node is destructed, all other nodes that
-// refer to anything in that tree become invalid.
+// those ``bdecode_node`` objects will simply have references to the root or
+// owning ``bdecode_node``. If the root node is destructed, all other nodes
+// that refer to anything in that tree become invalid.
//
// However, the underlying buffer passed in to this function (``start``, ``end``)
// must also remain valid while the bdecoded tree is used. The parsed tree
diff --git a/include/libtorrent/bencode.hpp b/include/libtorrent/bencode.hpp
index 16b86414a..e0e0f17c0 100644
--- a/include/libtorrent/bencode.hpp
+++ b/include/libtorrent/bencode.hpp
@@ -38,44 +38,38 @@ POSSIBILITY OF SUCH DAMAGE.
// OVERVIEW
//
-// Bencoding is a common representation in bittorrent used for
-// for dictionary, list, int and string hierarchies. It's used
-// to encode .torrent files and some messages in the network
-// protocol. libtorrent also uses it to store settings, resume
-// data and other state between sessions.
+// Bencoding is a common representation in bittorrent used for for dictionary,
+// list, int and string hierarchies. It's used to encode .torrent files and
+// some messages in the network protocol. libtorrent also uses it to store
+// settings, resume data and other state between sessions.
//
-// Strings in bencoded structures are not necessarily representing
-// text. Strings are raw byte buffers of a certain length. If a
-// string is meant to be interpreted as text, it is required to
-// be UTF-8 encoded. See `BEP 3`_.
+// Strings in bencoded structures are not necessarily representing text.
+// Strings are raw byte buffers of a certain length. If a string is meant to be
+// interpreted as text, it is required to be UTF-8 encoded. See `BEP 3`_.
//
// There are two mechanims to *decode* bencoded buffers in libtorrent.
//
// The most flexible one is `bdecode() bencode()`_, which returns a structure
-// represented by entry. When a buffer is decoded with this function,
-// it can be discarded. The entry does not contain any references back
-// to it. This means that bdecode() actually copies all the data out
-// of the buffer and into its own hierarchy. This makes this
-// function potentially expensive, if you're parsing large amounts
-// of data.
+// represented by entry. Oncea buffer has been decoded with this function, it
+// can be discarded. The entry does not contain any references back to it. This
+// means that bdecode() copies all the data out of the buffer and into its own
+// hierarchy. This makes this function expensive, which might matter if you're
+// parsing large amounts of data.
//
// Another consideration is that `bdecode() bencode()`_ is a recursive parser.
-// For this reason, in order to avoid DoS attacks by triggering
-// a stack overflow, there is a recursion limit. This limit is
-// a sanity check to make sure it doesn't run the risk of
-// busting the stack.
+// For this reason, in order to avoid DoS attacks by triggering a stack
+// overflow, there is a recursion limit. This limit is a sanity check to make
+// sure it doesn't run the risk of busting the stack.
//
-// The second mechanism is bdecode(), which returns a
-// bencoded structure represented by bdecode_node. This function
-// builds a tree that points back into the original buffer.
-// The returned bdecode_node will not be valid once the buffer
-// it was parsed out of is discarded.
+// The second mechanism is the decode function for bdecode_node. This function
+// builds a tree that points back into the original buffer. The returned
+// bdecode_node will not be valid once the buffer it was parsed out of is
+// discarded.
//
-// Not only is this function more efficient because of less
-// memory allocation and data copy, the parser is also not
-// recursive, which means it probably performs a little bit
-// better and can have a higher recursion limit on the structures
-// it's parsing.
+// Not only is this function more efficient because of less memory allocation
+// and data copy, the parser is also not recursive, which means it probably
+// performs a little bit better and can have a higher recursion limit on the
+// structures it's parsing.
#include
#include
diff --git a/include/libtorrent/block_cache.hpp b/include/libtorrent/block_cache.hpp
index 066756023..0ab4d5dbd 100644
--- a/include/libtorrent/block_cache.hpp
+++ b/include/libtorrent/block_cache.hpp
@@ -321,6 +321,7 @@ namespace libtorrent
#endif
};
+ // internal
inline std::size_t hash_value(cached_piece_entry const& p)
{
return std::size_t(p.storage.get()) + std::size_t(p.piece);
diff --git a/include/libtorrent/escape_string.hpp b/include/libtorrent/escape_string.hpp
index b87c2f9ed..cbd8cd201 100644
--- a/include/libtorrent/escape_string.hpp
+++ b/include/libtorrent/escape_string.hpp
@@ -80,14 +80,13 @@ namespace libtorrent
TORRENT_EXTRA_EXPORT bool is_hex(char const *in, int len);
- // converts (binary) the string ``s`` to hexadecimal representation and
- // returns it.
+ // The overload taking a ``std::string`` converts (binary) the string ``s``
+ // to hexadecimal representation and returns it.
+ // The overload taking a ``char const*`` and a length converts the binary
+ // buffer [``in``, ``in`` + len) to hexadecimal and prints it to the buffer
+ // ``out``. The caller is responsible for making sure the buffer pointed to
+ // by ``out`` is large enough, i.e. has at least len * 2 bytes of space.
TORRENT_EXPORT std::string to_hex(std::string const& s);
-
- // converts the binary buffer [``in``, ``in`` + len) to hexadecimal
- // and prints it to the buffer ``out``. The caller is responsible for
- // making sure the buffer pointed to by ``out`` is large enough,
- // i.e. has at least len * 2 bytes of space.
TORRENT_EXPORT void to_hex(char const *in, int len, char* out);
// converts the buffer [``in``, ``in`` + len) from hexadecimal to
diff --git a/include/libtorrent/peer_info.hpp b/include/libtorrent/peer_info.hpp
index 84dad29ed..5f8054336 100644
--- a/include/libtorrent/peer_info.hpp
+++ b/include/libtorrent/peer_info.hpp
@@ -216,7 +216,7 @@ namespace libtorrent
};
// a combination of flags describing from which sources this peer
- // was received.
+ // was received. See peer_source_flags.
boost::uint32_t source;
// the current upload and download speed we have to and from this peer
@@ -305,7 +305,7 @@ namespace libtorrent
// the kind of connection this is. Used for the connection_type field.
enum connection_type_t
{
- // Regular bittorrent connection over TCP
+ // Regular bittorrent connection
standard_bittorrent = 0,
// HTTP connection using the `BEP 19`_ protocol
diff --git a/include/libtorrent/sha1_hash.hpp b/include/libtorrent/sha1_hash.hpp
index 1dc1f05e7..439726d39 100644
--- a/include/libtorrent/sha1_hash.hpp
+++ b/include/libtorrent/sha1_hash.hpp
@@ -69,6 +69,7 @@ namespace libtorrent
{
enum { number_size = 5 };
public:
+ // internal
// the number of bytes of the number
static const int size = number_size * sizeof(boost::uint32_t);
diff --git a/include/libtorrent/string_util.hpp b/include/libtorrent/string_util.hpp
index a6420b66e..ac2545685 100644
--- a/include/libtorrent/string_util.hpp
+++ b/include/libtorrent/string_util.hpp
@@ -40,8 +40,11 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent
{
TORRENT_EXTRA_EXPORT bool is_alpha(char c);
- // this is used by bdecode_recursive's header file
- TORRENT_EXPORT bool is_digit(char c);
+
+ // internal
+ inline bool is_digit(char c)
+ { return c >= '0' && c <= '9'; }
+
TORRENT_EXTRA_EXPORT bool is_print(char c);
TORRENT_EXTRA_EXPORT bool is_space(char c);
TORRENT_EXTRA_EXPORT char to_lower(char c);
diff --git a/include/libtorrent/utf8.hpp b/include/libtorrent/utf8.hpp
index 2a875d6b9..9490b3551 100644
--- a/include/libtorrent/utf8.hpp
+++ b/include/libtorrent/utf8.hpp
@@ -45,6 +45,7 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent
{
+ // internal
// results from UTF-8 conversion functions utf8_wchar and
// wchar_utf8
enum utf8_conv_result_t
diff --git a/src/entry.cpp b/src/entry.cpp
index d7402c942..028ead032 100644
--- a/src/entry.cpp
+++ b/src/entry.cpp
@@ -131,15 +131,15 @@ namespace libtorrent
#ifndef BOOST_NO_EXCEPTIONS
const entry& entry::operator[](char const* key) const
{
- dictionary_type::const_iterator i = dict().find(key);
- if (i == dict().end()) throw type_error(
- (std::string("key not found: ") + key).c_str());
- return i->second;
+ return (*this)[std::string(key)];
}
const entry& entry::operator[](std::string const& key) const
{
- return (*this)[key.c_str()];
+ dictionary_type::const_iterator i = dict().find(key);
+ if (i == dict().end()) throw type_error(
+ (std::string("key not found: ") + key).c_str());
+ return i->second;
}
#endif
diff --git a/src/string_util.cpp b/src/string_util.cpp
index 2ffce0e48..60d0567fe 100644
--- a/src/string_util.cpp
+++ b/src/string_util.cpp
@@ -45,11 +45,6 @@ namespace libtorrent
return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
}
- bool is_digit(char c)
- {
- return c >= '0' && c <= '9';
- }
-
bool is_print(char c)
{
return c >= 32 && c < 127;