wornvirtue
/
premiere-libtorrent
forked from premiere/premiere-libtorrent
1
0
Fork 0
Code Pull Requests Activity

documetation fixes and polish

This commit is contained in:
Arvid Norberg 2015-03-14 21:55:26 +00:00
parent b237458183
commit fad1c42970
17 changed files with 115 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/gen_reference_doc.py
View File

@ -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<a name="%s"></a>' % 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()

2
docs/makefile
View File

@ -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 \

1
docs/manual.rst
View File

@ -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

4
docs/rst.css
View File

@ -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; }

59
docs/stats_counters.rst
View File

@ -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``).
<a name="peer.connreset_peers"></a>
<a name="peer.connrefused_peers"></a>
<a name="peer.connaborted_peers"></a>
<a name="peer.notconnected_peers"></a>
<a name="peer.perm_peers"></a>
<a name="peer.buffer_peers"></a>
<a name="peer.unreachable_peers"></a>
@ -59,33 +62,35 @@ disconnected initiated by this client (``disconnected_peers``).
<a name="peer.invalid_arg_peers"></a>
<a name="peer.aborted_peers"></a>
+------------------------+---------+
| 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

3
docs/style.css
View File

@ -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;
}

3
include/libtorrent/add_torrent_params.hpp
View File

@ -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

36
include/libtorrent/bdecode.hpp
View File

@ -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<std::string, bdecode_node> 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

52
include/libtorrent/bencode.hpp
View File

@ -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 <stdlib.h>
#include <string>

1
include/libtorrent/block_cache.hpp
View File

@ -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);

13
include/libtorrent/escape_string.hpp
View File

@ -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

4
include/libtorrent/peer_info.hpp
View File

@ -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

1
include/libtorrent/sha1_hash.hpp
View File

@ -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);

7
include/libtorrent/string_util.hpp
View File

@ -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);

1
include/libtorrent/utf8.hpp
View File

@ -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

10
src/entry.cpp
View File

@ -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

5
src/string_util.cpp
View File

@ -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;