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

updated documentation for add_torrent

This commit is contained in:
Arvid Norberg 2007-11-20 07:54:51 +00:00
parent 55fac2518d
commit 94d9f09d8a
2 changed files with 91 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
docs/manual.html
View File

@ -164,17 +164,18 @@
</li> </li>
<li><a class="reference" href="#threads" id="id136" name="id136">threads</a></li> <li><a class="reference" href="#threads" id="id136" name="id136">threads</a></li>
<li><a class="reference" href="#storage-allocation" id="id137" name="id137">storage allocation</a><ul> <li><a class="reference" href="#storage-allocation" id="id137" name="id137">storage allocation</a><ul>
<li><a class="reference" href="#full-allocation" id="id138" name="id138">full allocation</a></li> <li><a class="reference" href="#sparse-allocation" id="id138" name="id138">sparse allocation</a></li>
<li><a class="reference" href="#compact-allocation" id="id139" name="id139">compact allocation</a></li> <li><a class="reference" href="#full-allocation" id="id139" name="id139">full allocation</a></li>
<li><a class="reference" href="#compact-allocation" id="id140" name="id140">compact allocation</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#extensions" id="id140" name="id140">extensions</a><ul> <li><a class="reference" href="#extensions" id="id141" name="id141">extensions</a><ul>
<li><a class="reference" href="#metadata-from-peers" id="id141" name="id141">metadata from peers</a></li> <li><a class="reference" href="#metadata-from-peers" id="id142" name="id142">metadata from peers</a></li>
<li><a class="reference" href="#http-seeding" id="id142" name="id142">HTTP seeding</a></li> <li><a class="reference" href="#http-seeding" id="id143" name="id143">HTTP seeding</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#filename-checks" id="id143" name="id143">filename checks</a></li> <li><a class="reference" href="#filename-checks" id="id144" name="id144">filename checks</a></li>
<li><a class="reference" href="#acknowledgments" id="id144" name="id144">acknowledgments</a></li> <li><a class="reference" href="#acknowledgments" id="id145" name="id145">acknowledgments</a></li>
</ul> </ul>
</div> </div>
<div class="section"> <div class="section">
@ -373,7 +374,7 @@ torrent_handle add_torrent(
torrent_info const&amp; ti torrent_info const&amp; ti
, boost::filesystem::path const&amp; save_path , boost::filesystem::path const&amp; save_path
, entry const&amp; resume_data = entry() , entry const&amp; resume_data = entry()
, bool compact_mode = true , storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false); , bool paused = false);
torrent_handle add_torrent( torrent_handle add_torrent(
@ -382,7 +383,7 @@ torrent_handle add_torrent(
, char const* name , char const* name
, boost::filesystem::path const&amp; save_path , boost::filesystem::path const&amp; save_path
, entry const&amp; resume_data = entry() , entry const&amp; resume_data = entry()
, bool compact_mode = true , storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false); , bool paused = false);
</pre> </pre>
</blockquote> </blockquote>
@ -396,12 +397,22 @@ for checking, being checked or downloading) <tt class="docutils literal"><span c
<p>The optional parameter, <tt class="docutils literal"><span class="pre">resume_data</span></tt> can be given if up to date fast-resume data <p>The optional parameter, <tt class="docutils literal"><span class="pre">resume_data</span></tt> can be given if up to date fast-resume data
is available. The fast-resume data can be acquired from a running torrent by calling is available. The fast-resume data can be acquired from a running torrent by calling
<tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt>. See <a class="reference" href="#fast-resume">fast resume</a>.</p> <tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt>. See <a class="reference" href="#fast-resume">fast resume</a>.</p>
<p>The <tt class="docutils literal"><span class="pre">compact_mode</span></tt> parameter refers to the layout of the storage for this torrent. If <p>The <tt class="docutils literal"><span class="pre">storage_mode</span></tt> parameter refers to the layout of the storage for this torrent.
set to true (default), the storage will grow as more pieces are downloaded, and pieces There are 3 different modes:</p>
<dl class="docutils">
<dt>storage_mode_sparse</dt>
<dd>All pieces will be written to the place where they belong and sparse files
will be used. This is the recommended, and default mode.</dd>
<dt>storage_mode_allocate</dt>
<dd>All pieces will be allocated, zeroes will be written to the files, before
the data is downloaded and written to the file. This might be useful for
filesystems that don't support sparse files.</dd>
<dt>storage_mode_compact</dt>
<dd>The storage will grow as more pieces are downloaded, and pieces
are rearranged to finally be in their correct places once the entire torrent has been are rearranged to finally be in their correct places once the entire torrent has been
downloaded. If it is false, the entire storage is allocated before download begins. I.e. downloaded.</dd>
the files contained in the torrent are filled with zeros, and each downloaded piece </dl>
is put in its final place directly when downloaded. For more info, see <a class="reference" href="#storage-allocation">storage allocation</a>.</p> <p>For more information, see <a class="reference" href="#storage-allocation">storage allocation</a>.</p>
<p><tt class="docutils literal"><span class="pre">paused</span></tt> is a boolean that specifies whether or not the torrent is to be started in <p><tt class="docutils literal"><span class="pre">paused</span></tt> is a boolean that specifies whether or not the torrent is to be started in
a paused state. I.e. it won't connect to the tracker or any of the peers until it's a paused state. I.e. it won't connect to the tracker or any of the peers until it's
resumed. This is typically a good way of avoiding race conditions when setting resumed. This is typically a good way of avoiding race conditions when setting
@ -415,6 +426,8 @@ with extensions enabled (<tt class="docutils literal"><span class="pre">TORRENT_
takes an optional <tt class="docutils literal"><span class="pre">name</span></tt> argument. This may be 0 in case no name should be assigned takes an optional <tt class="docutils literal"><span class="pre">name</span></tt> argument. This may be 0 in case no name should be assigned
to the torrent. In case it's not 0, the name is used for the torrent as long as it doesn't to the torrent. In case it's not 0, the name is used for the torrent as long as it doesn't
have metadata. See <tt class="docutils literal"><span class="pre">torrent_handle::name</span></tt>.</p> have metadata. See <tt class="docutils literal"><span class="pre">torrent_handle::name</span></tt>.</p>
<p>If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
<tt class="docutils literal"><span class="pre">tracker_url</span></tt> can be 0.</p>
</div> </div>
<div class="section"> <div class="section">
<h2><a id="remove-torrent-find-torrent-get-torrents" name="remove-torrent-find-torrent-get-torrents">remove_torrent() find_torrent() get_torrents()</a></h2> <h2><a id="remove-torrent-find-torrent-get-torrents" name="remove-torrent-find-torrent-get-torrents">remove_torrent() find_torrent() get_torrents()</a></h2>
@ -3498,25 +3511,34 @@ non-blocking host name resolution to simulate non-blocking behavior.</li>
</div> </div>
<div class="section"> <div class="section">
<h1><a id="storage-allocation" name="storage-allocation">storage allocation</a></h1> <h1><a id="storage-allocation" name="storage-allocation">storage allocation</a></h1>
<p>There are two modes in which storage (files on disk) are allocated in libtorrent.</p> <p>There are three modes in which storage (files on disk) are allocated in libtorrent.</p>
<blockquote> <ol class="arabic simple">
<ul class="simple">
<li>The traditional <em>full allocation</em> mode, where the entire files are filled up with <li>The traditional <em>full allocation</em> mode, where the entire files are filled up with
zeros before anything is downloaded. libtorrent will look for sparse files support zeros before anything is downloaded. libtorrent will look for sparse files support
in the filesystem that is used for storage, and use sparse files or file system in the filesystem that is used for storage, and use sparse files or file system
zero fill support if present. This means that on NTFS, full allocation mode will zero fill support if present. This means that on NTFS, full allocation mode will
only allocate storage for the downloaded pieces.</li> only allocate storage for the downloaded pieces.</li>
<li>And the <em>compact allocation</em> mode, where only files are allocated for actual <li>The <em>compact allocation</em> mode, where only files are allocated for actual
pieces that have been downloaded. This is the default allocation mode in libtorrent.</li> pieces that have been downloaded. This is the default allocation mode in libtorrent.</li>
</ul> <li>The <em>sparce allocation</em>, sparse files are used, and pieces are downloaded directly
</blockquote> to where they belong. This is the recommended (and default) mode.</li>
<p>The allocation mode is selected when a torrent is started. It is passed as a boolean </ol>
argument to <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> (see <a class="reference" href="#add-torrent">add_torrent()</a>). These two modes have <p>The allocation mode is selected when a torrent is started. It is passed as an
different drawbacks and benefits.</p> argument to <tt class="docutils literal"><span class="pre">session::add_torrent()</span></tt> (see <a class="reference" href="#add-torrent">add_torrent()</a>).</p>
<p>The decision to use full allocation or compact allocation typically depends on whether <p>The decision to use full allocation or compact allocation typically depends on whether
any files are filtered and if the filesystem supports sparse files.</p> any files are filtered and if the filesystem supports sparse files.</p>
<p>To know if the filesystem supports sparse files (and to know if libtorrent believes the <div class="section">
filesystem supports sparse files), see <a class="reference" href="#supports-sparse-files">supports_sparse_files()</a>.</p> <h2><a id="sparse-allocation" name="sparse-allocation">sparse allocation</a></h2>
<p>On filesystems that supports sparse files, this allocation mode will only use
as much space as has been downloaded.</p>
<blockquote>
<ul class="simple">
<li>It does not require an allocation pass on startup.</li>
<li>It supports skipping files (setting prioirty to 0 to not download).</li>
<li>Fast resume data will remain valid even when file time stamps are out of date.</li>
</ul>
</blockquote>
</div>
<div class="section"> <div class="section">
<h2><a id="full-allocation" name="full-allocation">full allocation</a></h2> <h2><a id="full-allocation" name="full-allocation">full allocation</a></h2>
<p>When a torrent is started in full allocation mode, the checker thread (see <a class="reference" href="#threads">threads</a>) <p>When a torrent is started in full allocation mode, the checker thread (see <a class="reference" href="#threads">threads</a>)

60
docs/manual.rst
View File

@ -208,7 +208,7 @@ add_torrent()
torrent_info const& ti torrent_info const& ti
, boost::filesystem::path const& save_path , boost::filesystem::path const& save_path
, entry const& resume_data = entry() , entry const& resume_data = entry()
, bool compact_mode = true , storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false); , bool paused = false);
torrent_handle add_torrent( torrent_handle add_torrent(
@ -217,7 +217,7 @@ add_torrent()
, char const* name , char const* name
, boost::filesystem::path const& save_path , boost::filesystem::path const& save_path
, entry const& resume_data = entry() , entry const& resume_data = entry()
, bool compact_mode = true , storage_mode_t storage_mode = storage_mode_sparse
, bool paused = false); , bool paused = false);
You add torrents through the ``add_torrent()`` function where you give an You add torrents through the ``add_torrent()`` function where you give an
@ -233,12 +233,24 @@ The optional parameter, ``resume_data`` can be given if up to date fast-resume d
is available. The fast-resume data can be acquired from a running torrent by calling is available. The fast-resume data can be acquired from a running torrent by calling
``torrent_handle::write_resume_data()``. See `fast resume`_. ``torrent_handle::write_resume_data()``. See `fast resume`_.
The ``compact_mode`` parameter refers to the layout of the storage for this torrent. If The ``storage_mode`` parameter refers to the layout of the storage for this torrent.
set to true (default), the storage will grow as more pieces are downloaded, and pieces There are 3 different modes:
are rearranged to finally be in their correct places once the entire torrent has been
downloaded. If it is false, the entire storage is allocated before download begins. I.e. storage_mode_sparse
the files contained in the torrent are filled with zeros, and each downloaded piece All pieces will be written to the place where they belong and sparse files
is put in its final place directly when downloaded. For more info, see `storage allocation`_. will be used. This is the recommended, and default mode.
storage_mode_allocate
All pieces will be allocated, zeroes will be written to the files, before
the data is downloaded and written to the file. This might be useful for
filesystems that don't support sparse files.
storage_mode_compact
The storage will grow as more pieces are downloaded, and pieces
are rearranged to finally be in their correct places once the entire torrent has been
downloaded.
For more information, see `storage allocation`_.
``paused`` is a boolean that specifies whether or not the torrent is to be started in ``paused`` is a boolean that specifies whether or not the torrent is to be started in
a paused state. I.e. it won't connect to the tracker or any of the peers until it's a paused state. I.e. it won't connect to the tracker or any of the peers until it's
@ -256,6 +268,10 @@ takes an optional ``name`` argument. This may be 0 in case no name should be ass
to the torrent. In case it's not 0, the name is used for the torrent as long as it doesn't to the torrent. In case it's not 0, the name is used for the torrent as long as it doesn't
have metadata. See ``torrent_handle::name``. have metadata. See ``torrent_handle::name``.
If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
``tracker_url`` can be 0.
remove_torrent() find_torrent() get_torrents() remove_torrent() find_torrent() get_torrents()
---------------------------------------------- ----------------------------------------------
@ -3618,26 +3634,38 @@ libtorrent starts 2 or 3 threads.
storage allocation storage allocation
================== ==================
There are two modes in which storage (files on disk) are allocated in libtorrent. There are three modes in which storage (files on disk) are allocated in libtorrent.
* The traditional *full allocation* mode, where the entire files are filled up with 1. The traditional *full allocation* mode, where the entire files are filled up with
zeros before anything is downloaded. libtorrent will look for sparse files support zeros before anything is downloaded. libtorrent will look for sparse files support
in the filesystem that is used for storage, and use sparse files or file system in the filesystem that is used for storage, and use sparse files or file system
zero fill support if present. This means that on NTFS, full allocation mode will zero fill support if present. This means that on NTFS, full allocation mode will
only allocate storage for the downloaded pieces. only allocate storage for the downloaded pieces.
* And the *compact allocation* mode, where only files are allocated for actual 2. The *compact allocation* mode, where only files are allocated for actual
pieces that have been downloaded. This is the default allocation mode in libtorrent. pieces that have been downloaded. This is the default allocation mode in libtorrent.
The allocation mode is selected when a torrent is started. It is passed as a boolean 3. The *sparce allocation*, sparse files are used, and pieces are downloaded directly
argument to ``session::add_torrent()`` (see `add_torrent()`_). These two modes have to where they belong. This is the recommended (and default) mode.
different drawbacks and benefits.
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 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 are filtered and if the filesystem supports sparse files.
To know if the filesystem supports sparse files (and to know if libtorrent believes the sparse allocation
filesystem supports sparse files), see `supports_sparse_files()`_. -----------------
On filesystems that supports sparse files, this allocation mode will only use
as much space as has been downloaded.
* It does not require an allocation pass on startup.
* It supports skipping files (setting prioirty to 0 to not download).
* Fast resume data will remain valid even when file time stamps are out of date.
full allocation full allocation
--------------- ---------------