diff --git a/docs/building.html b/docs/building.html index f17bcb223..57c030acb 100644 --- a/docs/building.html +++ b/docs/building.html @@ -328,18 +328,20 @@ sent to and received from UPnP devices. -
In some circumstances, the disk cache may not suffice to provide maximum performance. +One such example is high performance seeding, to a large number of peers, over a fast +up-link. In such a case, the amount of RAM may simply not be enough to cache disk +reads. When there's not enough RAM to cache disk reads, the disk throughput would +typically degrade to perform as poorly as with no cache at all, with the majority +of the time spent waiting for the disk head to seek.
+To solve this problem, libtorrent sorts read requests by their physical offset on the +disk. They are processed by having the disk read head sweep back and forth over the drive.
+This makes libtorrent very suitable for large scale, high-throughput seeding.
+These plots illustrates the physical disk offset for reads over time. The left plot +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.
+On CPUs with small L2 caches, copying memory can be expensive operations. It is important diff --git a/docs/make_torrent.html b/docs/make_torrent.html index 52fb6c586..3ac9a7945 100644 --- a/docs/make_torrent.html +++ b/docs/make_torrent.html @@ -42,24 +42,25 @@
Table of contents
+++void add_file(file_entry const& e); +void add_file(fs::path const& p, size_type size); ++
Adds a file to the file storage. If more files than one are added, +certain restrictions to their paths apply. In a multi-file file +storage (torrent), all files must share the same root directory.
+That is, the first path element of all files must be the same. +This shared path element is also set to the name of the torrent. It +can be changed by calling set_name.
+The built in functions to traverse a directory to add files will +make sure this requirement is fulfilled.
+@@ -315,6 +333,23 @@ entry generate() const; generate the flat file, use the bencode() function.It may be useful to add custom entries to the torrent file before bencoding it and saving it to disk.
+If anything goes wrong during torrent generation, this function will return +an empty entry structure. You can test for this condition by querying the +type of the entry:
++file_storage fs; +// add file ... +create_torrent t(fs); +// add trackers and piece hashes ... +e = t.generate(); + +if (e.type() == entry::undefined_t) +{ + // something went wrong +} ++For instance, you cannot generate a torrent with 0 files in it. If you don't add +any files to the file_storage, torrent generation will fail.
dht_nodes, dht_cache_nodes and dht_torrents are only available when +
dht_nodes, dht_node_cache and dht_torrents are only available when built with DHT support. They are all set to 0 if the DHT isn't running. When the DHT is running, dht_nodes is set to the number of nodes in the routing table. This number only includes active nodes, not cache nodes. The -dht_cache_nodes is set to the number of nodes in the node cache. These nodes +dht_node_cache is set to the number of nodes in the node cache. These nodes are used to replace the regular nodes in the routing table in case any of them becomes unresponsive.
dht_torrents are the number of torrents tracked by the DHT at the moment.
@@ -2716,14 +2716,14 @@ while (num_resume_data > 0) std::auto_ptr<alert> holder = ses.pop_alert(); - if (dynamic_cast<save_resume_data_failed_alert const*>(a)) + if (alert_cast<save_resume_data_failed_alert>(a)) { process_alert(a); --num_resume_data; continue; } - save_resume_data_alert const* rd = dynamic_cast<save_resume_data_alert const*>(a); + save_resume_data_alert const* rd = alert_cast<save_resume_data_alert>(a); if (rd == 0) { process_alert(a); @@ -4566,9 +4566,14 @@ or upload rate.Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable all alerts
-When you get an alert, you can use typeid() or dynamic_cast<> to get more detailed -information on exactly which type it is. i.e. what kind of error it is. You can also use a -dispatcher mechanism that's available in libtorrent.
+When you get an alert, you can use alert_cast<> to attempt to cast the pointer to a +more specific alert type, to be queried for more information about the alert. alert_cast +has the followinf signature:
++template <T> T* alert_cast(alert* a); +template <T> T const* alert_cast(alert const* a); ++
You can also use a dispatcher mechanism that's available in libtorrent.
All alert types are defined in the <libtorrent/alert_types.hpp> header file.
The alert class is the base class that specific messages are derived from. This is its synopsis: