diff --git a/docs/building.html b/docs/building.html index 928a089ff..8e674e0a0 100644 --- a/docs/building.html +++ b/docs/building.html @@ -36,19 +36,19 @@ Author: -Arvid Norberg, arvid@rasterbar.com +Arvid Norberg, arvid@rasterbar.com

Table of contents

@@ -3956,7 +4055,7 @@ been posted by libtorrent pop_ale auto_ptr object. If there is an alert in libtorrent's queue, the alert from the front of the queue is popped and returned. You can then use the alert object and query

-

By default, only errors are reported. session::set_alert_mask() can be +

By default, only errors are reported. set_alert_mask() can be used to specify which kinds of events should be reported. The alert mask is a bitmask with the following bits:

@@ -4021,7 +4120,7 @@ alerts that belong to an enabled category are posted. Setting the alert bitmask 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.

+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:

@@ -4084,6 +4183,24 @@ struct tracker_alert: torrent_alert };

The specific alerts are:

+
+

read_piece_alert

+

This alert is posted when the asynchronous read operation initiated by +a call to read_piece() is completed. If the read failed, the torrent +is paused and an error state is set and the buffer member of the alert +is 0. If successful, buffer points to a buffer containing all the data +of the piece. piece is the piece index that was read. size is the +number of bytes that was read.

+
+struct read_piece_alert: torrent_alert
+{
+        // ...
+        boost::shared_ptr<char> buffer;
+        int piece;
+        int size;
+};
+
+

external_ip_alert

Whenever libtorrent learns about the machines external IP, this alert is @@ -4101,7 +4218,7 @@ struct external_ip_alert: alert

listen_failed_alert

This alert is generated when none of the ports, given in the port range, to -session can be opened for listening. This alert doesn't have any extra +session can be opened for listening. This alert doesn't have any extra data members.

@@ -4113,7 +4230,7 @@ case it appears the client is not running on a NAT:ed network or if it appears there is no NAT router that can be remote controlled to add port mappings.

mapping refers to the mapping index of the port map that failed, i.e. -the index returned from add_mapping.

+the index returned from add_mapping.

type is 0 for NAT-PMP and 1 for UPnP.

 struct portmap_error_alert: alert
@@ -4131,7 +4248,7 @@ a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP
 capable router, this is typically generated once when mapping the TCP
 port and, if DHT is enabled, when the UDP port is mapped.

 
mapping refers to the mapping index of the port map that failed, i.e.
-the index returned from add_mapping.

+the index returned from add_mapping.

 
external_port is the external port allocated for the mapping.

 
type is 0 for NAT-PMP and 1 for UPnP.

 
@@ -4334,7 +4451,7 @@ struct peer_error_alert: torrent_alert
 

 
invalid_request_alert

 
This is a debug alert that is generated by an incoming invalid piece request.
-ìp is the address of the peer and the request is the actual incoming
+Ïp is the address of the peer and the request is the actual incoming
 request from the peer.

 
 struct invalid_request_alert: torrent_alert
@@ -4578,7 +4695,7 @@ including <libtorrent/alert.hp
 here's a complete list with description.

 

 
invalid_handle

-
This exception is thrown when querying information from a torrent_handle that hasn't
+
This exception is thrown when querying information from a torrent_handle that hasn't
 been initialized or that has become invalid.

 
 struct invalid_handle: std::exception
@@ -4589,8 +4706,8 @@ struct invalid_handle: std::exception
 

 

 
duplicate_torrent

-
This is thrown by add_torrent() if the torrent already has been added to
-the session. Since remove_torrent() is asynchronous, this exception may
+
This is thrown by add_torrent() if the torrent already has been added to
+the session. Since remove_torrent() is asynchronous, this exception may
 be thrown if the torrent is removed and then immediately added again.

 
 struct duplicate_torrent: std::exception
@@ -4641,8 +4758,8 @@ this:

 struct storage_interface
 {
         virtual bool initialize(bool allocate_files) = 0;
-        virtual int read(char* buf, int slot, int offset, int size) = 0;
-        virtual int write(const char* buf, int slot, int offset, int size) = 0;
+        virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
+        virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
         virtual bool move_storage(fs::path save_path) = 0;
         virtual bool verify_resume_data(lazy_entry const& rd, std::string& error) = 0;
         virtual bool write_resume_data(entry& rd) const = 0;
@@ -4668,27 +4785,51 @@ will create directories and empty files at this point. If ftruncate all files to their target size.

 
Returning true indicates an error occurred.

 

-

-
read()

+

+
readv()

 

 
-int read(char* buf, int slot, int offset, int size) = 0;
+int readv(file::iovec_t const* buf, int slot, int offset, int num_bufs) = 0;
 

 

-
This function should read the data in the given slot and at the given offset
-and size number of bytes. The data is to be copied to buf.

+
This function should read the data in the given slot and at the given offset.
+It should read num_bufs buffers, where the size of each buffer is specified in the
+buffer array bufs. The file::iovec_t type has the following members:

+
+struct iovec_t
+{
+        void* iov_base;
+        size_t iov_len;
+};
+

 
The return value is the number of bytes actually read.

+
Every buffer in bufs can be assumed to be page aligned and be of a page aligned size,
+except for the last buffer of the torrent. The buffer can be assumed to fit a fully page
+aligned number of bytes though.

 

-

-
write()

+

+
writev()

 

 
 int write(const char* buf, int slot, int offset, int size) = 0;
 

 

-
This function should write the data in buf to the given slot (slot) at offset
-offset in that slot. The buffer size is size.

+
This function should write the data to the given slot and at the given offset.
+It should write num_bufs buffers, where the size of each buffer is specified in the
+buffer array bufs. The file::iovec_t type has the following members:

+
+struct iovec_t
+{
+        void* iov_base;
+        size_t iov_len;
+};
+

 
The return value is the number of bytes actually written.

+
Every buffer in bufs can be assumed to be page aligned and be of a page aligned size,
+except for the last buffer of the torrent. The buffer can be assumed to fit a fully page
+aligned number of bytes though.
+This function should write the data in buf to the given slot (slot) at offset
+offset in that slot. The buffer size is size.

 

 

 
move_storage()

@@ -4838,9 +4979,9 @@ torrents are being downloaded at any given time, and once a torrent is completel
 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 add_torrent()).

+torrent (see 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
@@ -4848,9 +4989,9 @@ that the number drops below the limit.

 
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

 
Torrents that are currently being downloaded or incomplete (with bytes still to download)
@@ -4863,7 +5004,7 @@ position in order to fill the gap.

 
Lower queue position means closer to the front of the queue, and will be started sooner than
 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() queue_position_bottom().

 

 

 
seeding

@@ -4873,20 +5014,20 @@ seeding. A seed cycle is completed when a torrent meets either the share ratio l
 (uploaded bytes / downloaded bytes), the share time ratio (time seeding / time
 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

 
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 add_torrent(), and it
+
To use the fast-resume data you simply give it to 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.

@@ -5008,14 +5149,11 @@ last resume data checkpoint.
 
  • The first thread is the main thread that will sit
 idle in a select() call most of the time. This thread runs the main loop
 that will send and receive data on all connections.
    • 
-
  • The second thread is a hash-check thread. Whenever a torrent is added it will
-first be passed to this thread for checking the files that may already have been
-downloaded. If there is any resume data this thread will make sure it is valid
-and matches the files. Once the torrent has been checked, it is passed on to the
-main thread that will start it. The hash-check thread has a queue of torrents,
-it will only check one torrent at a time.
    • 
-
  • The third thread is spawned by asio on systems that don't support
-non-blocking host name resolution to simulate non-blocking behavior.
    • 
+
  • The second thread is the disk I/O thread. All disk read and write operations
+are passed to this thread and messages are passed back to the main thread when
+the operation compeltes. The disk thread also verifies the piece hashes.
    • 
+
  • The third and forth threads are spawned by asio on systems that don't support
+non-blocking host name resolution to simulate non-blocking getaddrinfo().
    • 
 
 
 
    
@@ -5034,7 +5172,7 @@ pieces that have been downloaded.
 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()).
    
+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.
    
 
    
@@ -5051,7 +5189,7 @@ as much space as has been downloaded.
    
 
    
 
    
 
    full allocation
    
-
    When a torrent is started in full allocation mode, the disk-io thread (see threads)
+
    When a torrent is started in full allocation mode, the disk-io thread (see threads)
 will make sure that the entire storage is allocated, and fill any gaps with zeros.
 This will be skipped if the filesystem supports sparse files or automatic zero filling.
 It will of course still check for existing pieces and fast resume data. The main
@@ -5132,7 +5270,7 @@ contain any piece), return that slot index.
 
    
 
    
 
    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).
    
@@ -5261,8 +5399,13 @@ doesn't have any metadata.
 
    
 
    
 
    HTTP seeding
    
-
    The HTTP seed extension implements this specification.
    
-
    The libtorrent implementation assumes that, if the URL ends with a slash
+
    There are two kinds of HTTP seeding. One with that assumes a smart
+(and polite) client and one that assumes a smart server. These
+are specified in BEP 19 and BEP 17 respectively.
    
+
    libtorrent supports both. In the libtorrent source code and API,
+BEP 19 urls are typically referred to as url seeds and BEP 17
+urls are typically referred to as HTTP seeds.
    
+
    The libtorrent implementation of BEP 19 assumes that, if the URL ends with a slash
 ('/'), the filename should be appended to it in order to request pieces from
 that file. The way this works is that if the torrent is a single-file torrent,
 only that filename is appended. If the torrent is a multi-file torrent, the
@@ -5279,17 +5422,17 @@ altogether. You can use:
    
 
     boost::filesystem::path::default_name_check(boost::filesystem::native);
 
    
-
    for example. For more information, see the Boost.Filesystem docs.
    
+
    for example. For more information, see the Boost.Filesystem docs.
    
 
    
 
    
 
    acknowledgments
    
-
    Written by Arvid Norberg. Copyright © 2003-2006
    
+
    Written by Arvid Norberg. Copyright © 2003-2008
    
 
    Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson
    
 
    Lots of testing, suggestions and contributions by Massaroddel and Tianhao Qiu.
    
 
    Big thanks to Michael Wojciechowski and Peter Koeleman for making the autotools
 scripts.
    
 
    Thanks to Reimond Retz for bugfixes, suggestions and testing
    
-
    Thanks to University of Umeå for providing development and test hardware.
    
+
    Thanks to University of Ume for providing development and test hardware.
    
 
    Project is hosted by sourceforge.