From 71886916747b95870fb8e39e4bab2daccd699d2d Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Fri, 19 Mar 2010 18:40:32 +0000 Subject: [PATCH] regenerated html --- docs/building.html | 2 +- docs/contributing.html | 2 +- docs/features.html | 5 +- docs/manual.html | 659 ++++++++++++++++++++++++++--------------- docs/tuning.html | 2 +- 5 files changed, 420 insertions(+), 250 deletions(-) diff --git a/docs/building.html b/docs/building.html index 052a5e320..7bd47e761 100644 --- a/docs/building.html +++ b/docs/building.html @@ -38,7 +38,7 @@ Author: Arvid Norberg, arvid@rasterbar.com Version: -0.15.0 +0.16.0
diff --git a/docs/contributing.html b/docs/contributing.html index e031148e0..64749656f 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -38,7 +38,7 @@ Author: Arvid Norberg, arvid@rasterbar.com Version: -0.15.0 +0.16.0
diff --git a/docs/features.html b/docs/features.html index d4eec518a..3c72e82a3 100644 --- a/docs/features.html +++ b/docs/features.html @@ -38,7 +38,7 @@ Author: Arvid Norberg, arvid@rasterbar.com Version: -0.15.0 +0.16.0
@@ -213,7 +213,8 @@ disk. They are processed by having the disk read head sweep back and forth over is of a run where disk operation re-ordering is turned off and the righ is when it's turned on. The right one has a relatively smooth sine wave shape whereas the left one is more random and involves much longer seeks back and forth over the disk.

-

True physical disk offset queries are only supported on newer linux kernels and Mac OS X.

+

True physical disk offset queries are only supported on newer linux kernels, Mac OS X and +Windows 2000 and up.

network buffers

diff --git a/docs/manual.html b/docs/manual.html index 4a2dc3edd..208ea175f 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -38,7 +38,7 @@ Author: Arvid Norberg, arvid@rasterbar.com Version: -0.15.0 +0.16.0
@@ -63,241 +63,240 @@
  • num_uploads() num_connections()
  • set_max_half_open_connections() max_half_open_connections()
  • load_asnum_db() load_country_db() int as_for_ip()
    • -
  • load_state() state()
    • -
  • set_ip_filter()
    • -
  • get_ip_filter()
    • -
  • status()
    • -
  • get_cache_status()
    • -
  • get_cache_info()
    • -
  • is_listening() listen_port() listen_on()
    • -
  • set_alert_mask()
    • -
  • pop_alert() wait_for_alert() set_alert_queue_size_limit()
    • -
  • add_extension()
    • -
  • set_settings() set_pe_settings()
    • -
  • set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()
    • -
  • peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()
    • -
  • set_i2p_proxy() i2p_proxy()
    • -
  • start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()
    • -
  • add_dht_node() add_dht_router()
    • -
  • start_lsd() stop_lsd()
    • -
  • start_upnp() stop_upnp()
    • -
  • start_natpmp() stop_natpmp()
    • +
  • set_ip_filter()
    • +
  • get_ip_filter()
    • +
  • status()
    • +
  • get_cache_status()
    • +
  • get_cache_info()
    • +
  • is_listening() listen_port() listen_on()
    • +
  • set_alert_mask()
    • +
  • pop_alert() wait_for_alert() set_alert_queue_size_limit()
    • +
  • add_extension()
    • +
  • set_settings() set_pe_settings()
    • +
  • set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()
    • +
  • peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()
    • +
  • set_i2p_proxy() i2p_proxy()
    • +
  • start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()
    • +
  • add_dht_node() add_dht_router()
    • +
  • start_lsd() stop_lsd()
    • +
  • start_upnp() stop_upnp()
    • +
  • start_natpmp() stop_natpmp()
    • -
  • entry
    • @@ -403,8 +402,22 @@ class session: public boost::noncopyable | add_default_plugins , int alert_mask = alert::error_notification); + enum save_state_flags_t + { + save_settings = 0x001, + save_dht_settings = 0x002, + save_dht_proxy = 0x004, + save_dht_state = 0x008, + save_i2p_proxy = 0x010, + save_encryption_settings = 0x020, + save_peer_proxy = 0x040, + save_web_proxy = 0x080, + save_tracker_proxy = 0x100, + save_as_map = 0x200, + }; + void load_state(lazy_entry const& e); - void save_state(entry& e) const; + void save_state(entry& e, boost::uint32_t flags) const; torrent_handle add_torrent( add_torrent_params const& params); @@ -471,9 +484,6 @@ class session: public boost::noncopyable bool load_country_db(wchar_t const* file); int as_for_ip(address const& adr); - void load_state(entry const& ses_state); - entry state() const; - void set_ip_filter(ip_filter const& f); ip_filter const& get_ip_filter() const; @@ -562,7 +572,7 @@ timeout can be set with set_setti 
     void load_state(lazy_entry const& e);
-void save_state(entry& e) const;
+void save_state(entry& e, boost::uint32_t flags) const;

    loads and saves all session settings, including dht_settings, encryption settings and proxy @@ -570,6 +580,24 @@ settings. save_state either not be initialized, or initialized as a dictionary.

    load_state expects a lazy_entry which can be built from a bencoded buffer with lazy_bdecode.

    +

    The flags arguments passed in to save_state can be used to filter which parts +of the session state to save. By default, all state is saved (except for the individual +torrents). These are the possible flags. A flag that's set, means those settings are saved:

    +
    +enum save_state_flags_t
+{
+        save_settings = 0x001,
+        save_dht_settings = 0x002,
+        save_dht_proxy = 0x004,
+        save_dht_state = 0x008,
+        save_i2p_proxy = 0x010,
+        save_encryption_settings = 0x020,
+        save_peer_proxy = 0x040,
+        save_web_proxy = 0x080,
+        save_tracker_proxy = 0x100,
+        save_as_map = 0x200,
+};
+

    pause() resume() is_paused()

    @@ -876,18 +904,6 @@ respectively. This will be used to look up which AS and country peers belong to. in the database or the ASN database is not loaded, 0 is returned.

    The wchar_t overloads are for wide character paths.

    -
    -

    load_state() state()

    -
    -
    -void load_state(entry const& ses_state);
-entry state() const;
-
    -
    -

    These functions loads and save session state. Currently, the only state -that's stored is peak download rates for ASes. This map is used to -determine which order to connect to peers.

    -

    set_ip_filter()

    @@ -1043,6 +1059,9 @@ struct cache_status int cache_size; int read_cache_size; int total_used_buffers; + int average_queue_time; + int average_read_time; + int job_queue_length; };
    @@ -1064,6 +1083,12 @@ This includes both read and write cache.

    total_used_buffers is the total number of buffers currently in use. This includes the read/write disk cache as well as send and receive buffers used in peer connections.

    +

    average_queue_time is the number of microseconds an average disk I/O job +has to wait in the job queue before it get processed.

    +

    average_read_time is the number of microseconds a read job takes to +wait in the queue and complete, in microseconds. This only includes +cache misses.

    +

    job_queue_length is the number of jobs in the job queue.

    get_cache_info()

    @@ -2025,7 +2050,14 @@ struct torrent_handle { torrent_handle(); - torrent_status status(); + enum status_flags_t + { + query_distributed_copies = 1, + query_accurate_download_counters = 2, + query_last_seen_complete = 4 + }; + + torrent_status status(boost::uint32_t flags = 0xffffffff); void file_progress(std::vector<size_type>& fp, int flags = 0); void get_download_queue(std::vector<partial_piece_info>& queue) const; void get_peer_info(std::vector<peer_info>& v) const; @@ -2858,12 +2890,35 @@ while (num_resume_data > 0)

    status()

    -torrent_status status() const;
+torrent_status status(boost::uint32_t flags = 0xffffffff) const;

    status() will return a structure with information about the status of this torrent. If the torrent_handle is invalid, it will throw libtorrent_exception exception. -See torrent_status.

    +See torrent_status. The flags argument filters what information is returned +in the torrent_status. Some information in there is relatively expensive to calculate, and +if you're not interested in it (and see performance issues), you can filter them out.

    +

    By default everything is included. The flags you can use to decide what to include are:

    +
      +
    • +
      query_distributed_copies
      +

      calculates distributed_copies, distributed_full_copies and distributed_fraction.

      +
      +
      +
      • +
    • +
      query_accurate_download_counters
      +

      includes partial downloaded blocks in total_done and total_wanted_done.

      +
      +
      +
      • +
    • +
      query_last_seen_complete
      +

      includes last_seen_complete.

      +
      +
      +
      • +

    get_download_queue()

    @@ -3068,6 +3123,10 @@ struct torrent_status bool upload_mode; int priority; + + time_t added_time; + time_t completed_time; + time_t last_seen_complete; };

    progress is a value in the range [0, 1], that represents the progress of the @@ -3123,7 +3182,8 @@ allocated. -

    When downloading, the progress is total_wanted_done / total_wanted.

    +

    When downloading, the progress is total_wanted_done / total_wanted. This takes +into account files whose priority have been set to 0. They are not considered.

    paused is set to true if the torrent is paused and false otherwise.

    error may be set to an error message describing why the torrent was paused, in case it was paused by an error. If the torrent is not paused or if it's paused but @@ -3189,9 +3249,9 @@ this does not necessarily has to be downloaded during this session (that's total_payload_download).

    total_wanted_done is the number of bytes we have downloaded, only counting the pieces that we actually want to download. i.e. excluding any pieces that we have but -are filtered as not wanted.

    +have priority 0 (i.e. not wanted).

    total_wanted is the total number of bytes we want to download. This is also -excluding pieces that have been filtered.

    +excluding pieces whose priorities have been set to 0.

    num_seeds is the number of peers that are seeding that this client is currently connected to.

    distributed_full_copies is the number of distributed copies of the torrent. @@ -3260,6 +3320,12 @@ hope that the disk condition (be it disk full or permission errors) has been resolved. If the torrent is not auto-managed, you have to explicitly take it out of the upload mode by calling set_upload_mode() on the torrent_handle.

    +

    added_time is the posix-time when this torrent was added. i.e. what +time(NULL) returned at the time.

    +

    completed_time is the posix-time when this torrent was finished. If +the torrent is not yet finished, this is 0.

    +

    last_seen_complete is the time when we, or one of our peers, last +saw a complete copy of this torrent.

    peer_info

    @@ -3669,6 +3735,7 @@ struct session_settings bool free_torrent_hashes; bool upnp_ignore_nonrouters; int send_buffer_watermark; + int send_buffer_watermark_factor; #ifndef TORRENT_NO_DEPRECATE bool auto_upload_slots; @@ -3692,7 +3759,16 @@ struct session_settings bool use_read_cache; bool explicit_read_cache; int explicit_cache_interval; - bool disk_io_no_buffer; + + enum io_buffer_mode_t + { + enable_os_cache = 0, + disable_os_cache_for_aligned_files = 1, + disable_os_cache = 2 + }; + int disk_io_write_mode; + int disk_io_read_mode; + std::pair<int, int> outgoing_ports; char peer_tos; @@ -3772,6 +3848,9 @@ struct session_settings bool incoming_starts_queued_torrents; bool report_true_downloaded; bool strict_end_game_mode; + + int default_peer_upload_rate; + int default_peer_download_rate; };

    user_agent this is the client identification to the tracker. @@ -3921,11 +4000,16 @@ cannot be passed back to add_t should ignore any broadcast response from a device whose address is not the configured router for this machine. i.e. it's a way to not talk to other people's routers by mistake.

    -

    send_buffer_waterbark is the upper limit of the send buffer low-watermark. +

    send_buffer_watermark is the upper limit of the send buffer low-watermark. if the send buffer has fewer bytes than this, we'll read another 16kB block onto it. If set too small, upload rate capacity will suffer. If set too high, memory will be wasted. The actual watermark may be lower than this in case the upload rate is low, this is the upper limit.

    +

    send_buffer_watermark_factor is multiplied to the peer's upload rate +to determine the low-watermark for the peer. This is clamped to not +exceed the send_buffer_watermark upper limit. This defaults to 1. +For high capacity connections, setting this higher can improve upload +performance and disk throughput.

    auto_upload_slots defaults to true. When true, if there is a global upload limit set and the current upload rate is less than 90% of that, another upload slot is opened. If the upload rate has been saturated for an extended period @@ -3964,10 +4048,12 @@ where they are only allowed to download whole pieces. If the whole piece a peer in parole mode fails the hash check, it is banned. If a peer participates in a piece that passes the hash check, it is taken out of parole mode.

    cache_size is the disk write and read cache. It is specified in units of -16 KiB blocks. It defaults to 1024 (= 16 MB). Buffers that are part of a peer's -send or receive buffer also count against this limit. Send and receive buffers -will never be denied to be allocated, but they will cause the actual cached blocks -to be flushed or evicted.

    +16 KiB blocks. Buffers that are part of a peer's send or receive buffer also +count against this limit. Send and receive buffers will never be denied to be +allocated, but they will cause the actual cached blocks to be flushed or evicted. +If this is set to -1, the cache size is automatically set to the amount +of physical RAM available in the machine divided by 8. If the amount of physical +RAM cannot be determined, it's set to 1024 (= 16 MiB).

    Disk buffers are allocated using a pool allocator, the number of blocks that are allocated at a time when the pool needs to grow can be specified in cache_buffer_chunk_size. This defaults to 16 blocks. Lower numbers @@ -3989,14 +4075,40 @@ read cache means scanning all pieces and picking a random set of the rarest ones There is an affinity to pick pieces that are already in the cache, so that subsequent refreshes only swaps in pieces that are rarer than whatever is in the cache at the time.

    -

    disk_io_no_buffer defaults to true. When set to true, files are preferred -to be opened in unbuffered mode. This helps the operating system from growing -its file cache indefinitely. Currently only files whose offset in the torrent -is page aligned are opened in unbuffered mode. A page is typically 4096 bytes -and since blocks in bittorrent are 16kB, any file that is aligned to a block -or piece will get the benefit of be opened in unbuffered mode. It is therefore -recommended to make the largest file in a torrent the first file (with offset 0) -or use pad files to align all files to piece boundries.

    +

    disk_io_write_mode and disk_io_read_mode determines how files are +opened when they're in read only mode versus read and write mode. The options +are:

    +
    +
      +
    • +
      enable_os_cache
      +

      This is the default and files are opened normally, with the OS caching +reads and writes.

      +
      +
      +
      • +
    • +
      disable_os_cache_for_aligned_files
      +

      This will open files in unbuffered mode for files where every read and +write would be sector aligned. Using aligned disk offsets is a requirement +on some operating systems.

      +
      +
      +
      • +
    • +
      disable_os_cache
      +

      This opens all files in unbuffered mode (if allowed by the operating system). +Linux and Windows, for instance, require disk offsets to be sector aligned, +and in those cases, this option is the same as disable_os_caches_for_aligned_files.

      +
      +
      +
      • +
    +
    +

    One reason to disable caching is that it may help the operating system from growing +its file cache indefinitely. Since some OSes only allow aligned files to be opened +in unbuffered mode, It is recommended to make the largest file in a torrent the first +file (with offset 0) or use pad files to align all files to piece boundries.

    outgoing_ports, if set to something other than (0, 0) is a range of ports used to bind outgoing sockets to. This may be useful for users whose router allows them to assign QoS classes to traffic based on its local port. It is @@ -4134,7 +4246,7 @@ data is read from the disk while checking. This may be useful for background tasks that doesn't matter if they take a bit longer, as long as they leave disk I/O time for other processes.

    disk_cache_algorithm tells the disk I/O thread which cache flush -algorithm to use. The default (and original) algorithm is LRU. This +algorithm to use. The default algorithm is largest_contiguous. This flushes the entire piece, in the write cache, that was least recently written to. This is specified by the session_settings::lru enum value. session_settings::largest_contiguous will flush the largest @@ -4247,6 +4359,12 @@ sometimes, but it may also avoid downloading a lot of redundant bytes. If this is false, libtorrent attempts to use each peer connection to its max, by always requesting something, even if it means requesting something that has been requested from another peer already.

    +

    default_peer_upload_rate and default_peer_download_rate specifies +the default upload and download rate limits for peers, respectively. These +default to 0, which means unlimited. These settings affect the rate limits +set on new peer connections (not existing ones). The peer rate limits can +be changed individually later using +set_peer_upload_limit() set_peer_download_limit().

    @@ -6382,6 +6500,57 @@ decompressing it failed +

    tracker errors:

    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    170scrape_not_availableThe tracker URL doesn't support transforming it into a scrape +URL. i.e. it doesn't contain "announce.
    171invalid_tracker_responseinvalid tracker response
    172invalid_peer_dictinvalid peer dictionary entry. Not a dictionary
    173tracker_failuretracker sent a failure message
    174invalid_files_entrymissing or invalid 'files' entry
    175invalid_hash_entrymissing or invalid 'hash' entry
    176invalid_peers_entrymissing or invalid 'peers' and 'peers6' entry
    177invalid_tracker_response_lengthudp tracker response packet has invalid size
    178invalid_tracker_transaction_idinvalid transaction id in udp tracker response
    179invalid_tracker_actioninvalid action field in udp tracker response

    The names of these error codes are declared in then libtorrent::errors namespace.

    There is also another error category, libtorrent::upnp_category, defining errors retrned by UPnP routers. Here's a (possibly incomplete) list of UPnP error codes:

    @@ -7053,7 +7222,7 @@ to where they belong. This is the recommended (and default) mode.

    The allocation mode is selected when a torrent is started. It is passed as an argument to session::add_torrent() (see add_torrent()).

    The decision to use full allocation or compact allocation typically depends on whether -any files are filtered and if the filesystem supports sparse files.

    +any files have priority 0 and if the filesystem supports sparse files.

    sparse allocation

    On filesystems that supports sparse files, this allocation mode will only use @@ -7094,7 +7263,7 @@ filesystems' file allocation, and reduce fragmentation. sparse files are being used.

  • The fast resume data will be more likely to be usable, regardless of crashes or out of date data, since pieces won't move around.
    • -
  • Can be used with the filter files feature.
    • +
  • Can be used with prioritizing files to 0.
    • @@ -7108,7 +7277,7 @@ download has all its pieces in the correct place). So, the main drawbacks are:
  • More disk operations while downloading since pieces are moved around.
  • Potentially more fragmentation in the filesystem.
    • -
  • Cannot be used while filtering files.
    • +
  • Cannot be used while having files with priority 0.

    • The benefits though, are:

    diff --git a/docs/tuning.html b/docs/tuning.html index 88d5e5c3e..e8cbe8770 100644 --- a/docs/tuning.html +++ b/docs/tuning.html @@ -38,7 +38,7 @@ Author: Arvid Norberg, arvid@rasterbar.com Version: -0.15.0 +0.16.0