<p>Declared in "<aclass="reference external"href="../include/libtorrent/file_pool.hpp">libtorrent/file_pool.hpp</a>"</p>
<p>this is an internal cache of open file handles. It's primarily used by
<aclass="reference external"href="reference-Custom_Storage.html#storage_interface">storage_interface</a> implementations. It provides semi weak guarantees of
not opening more file handles than specified. Given multiple threads,
each with the ability to lock a file handle (via smart pointer), there
may be windows where more file handles are open.</p>
<preclass="literal-block">
struct file_pool : boost::noncopyable
{
<strong>~file_pool</strong> ();
<strong>file_pool</strong> (int size = 40);
boost::intrusive_ptr<file><strong>open_file</strong> (void* st, std::string const& p
, int file_index, file_storage const& fs, int m, error_code& ec);
void <strong>release</strong> (void* st);
void <strong>release</strong> (void* st, int file_index);
<p><ttclass="docutils literal">size</tt> specifies the number of allowed files handles
to hold open at any given time.</p>
<aname="open_file()"></a></div>
<divclass="section"id="open-file">
<h2>open_file()</h2>
<preclass="literal-block">
boost::intrusive_ptr<file><strong>open_file</strong> (void* st, std::string const& p
, int file_index, file_storage const& fs, int m, error_code& ec);
</pre>
<p>return an open file handle to file at <ttclass="docutils literal">file_index</tt> in the
<aclass="reference external"href="reference-Storage.html#file_storage">file_storage</a><ttclass="docutils literal">fs</tt> opened at save path <ttclass="docutils literal">p</tt>. <ttclass="docutils literal">m</tt> is the
file open mode (see <aclass="reference external"href="file::open_mode_t">file::open_mode_t</a>).</p>
<aname="release()"></a></div>
<divclass="section"id="release">
<h2>release()</h2>
<preclass="literal-block">
void <strong>release</strong> (void* st);
void <strong>release</strong> (void* st, int file_index);
</pre>
<p>release all files belonging to the specified <aclass="reference external"href="reference-Custom_Storage.html#storage_interface">storage_interface</a> (<ttclass="docutils literal">st</tt>)
the overload that takes <ttclass="docutils literal">file_index</tt> releases only the file with
that index in storage <ttclass="docutils literal">st</tt>.</p>
<aname="resize()"></a></div>
<divclass="section"id="resize">
<h2>resize()</h2>
<preclass="literal-block">
void <strong>resize</strong> (int size);
</pre>
<p>update the allowed number of open file handles to <ttclass="docutils literal">size</tt>.</p>
<aname="size_limit()"></a></div>
<divclass="section"id="size-limit">
<h2>size_limit()</h2>
<preclass="literal-block">
int <strong>size_limit</strong> () const;
</pre>
<p>returns the current limit of number of allowed open file handles held
by the <aclass="reference external"href="reference-Custom_Storage.html#file_pool">file_pool</a>.</p>
<aname="storage_interface"></a></div>
</div>
<divclass="section"id="storage-interface">
<h1>storage_interface</h1>
<p>Declared in "<aclass="reference external"href="../include/libtorrent/storage.hpp">libtorrent/storage.hpp</a>"</p>
<p>The storage interface is a pure virtual class that can be implemented to
customize how and where data for a torrent is stored. The default storage
implementation uses regular files in the filesystem, mapping the files in the
torrent in the way one would assume a torrent is saved to disk. Implementing
your own storage interface makes it possible to store all data in RAM, or in
some optimized order on disk (the order the pieces are received for instance),
or saving multifile torrents in a single file in order to be able to take
advantage of optimized disk-I/O.</p>
<p>It is also possible to write a thin class that uses the default storage but
modifies some particular behavior, for instance encrypting the data before
it's written to disk, and decrypting it when it's read again.</p>
<p>The storage interface is based on slots, each slot is 'piece_size' number
of bytes. All access is done by writing and reading whole or partial
slots. One slot is one piece in the torrent, but the data in the slot
does not necessarily correspond to the piece with the same index (in
compact allocation mode it won't).</p>
<p>libtorrent comes with two built-in storage implementations; <ttclass="docutils literal">default_storage</tt>
and <ttclass="docutils literal">disabled_storage</tt>. Their constructor functions are called <aclass="reference external"href="reference-Storage.html#default_storage_constructor()">default_storage_constructor()</a>
and <ttclass="docutils literal">disabled_storage_constructor</tt> respectively. The disabled storage does
just what it sounds like. It throws away data that's written, and it
reads garbage. It's useful mostly for benchmarking and profiling purpose.</p>
virtual int <strong>writev</strong> (<aclass="reference external"href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <aclass="reference external"href="file::random_access">file::random_access</a>);
virtual int <strong>readv</strong> (<aclass="reference external"href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <aclass="reference external"href="file::random_access">file::random_access</a>);
<p>This function is called when first checking (or re-checking) the storage for a torrent.
It should return true if any of the files that is used in this storage exists on disk.
If so, the storage will be checked for existing pieces before starting the download.</p>
<aname="writev()"></a>
<aname="readv()"></a></div>
<divclass="section"id="writev-readv">
<h2>writev() readv()</h2>
<preclass="literal-block">
virtual int <strong>writev</strong> (<aclass="reference external"href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <aclass="reference external"href="file::random_access">file::random_access</a>);
virtual int <strong>readv</strong> (<aclass="reference external"href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <aclass="reference external"href="file::random_access">file::random_access</a>);
</pre>
<p>These functions should read or write the data in or to the given <ttclass="docutils literal">slot</tt> at the given <ttclass="docutils literal">offset</tt>.
It should read or write <ttclass="docutils literal">num_bufs</tt> buffers sequentially, where the size of each buffer
is specified in the buffer array <ttclass="docutils literal">bufs</tt>. The <aclass="reference external"href="file::iovec_t">file::iovec_t</a> type has the following members:</p>
<preclass="literal-block">
struct iovec_t
{
void* iov_base;
size_t iov_len;
};
</pre>
<p>The return value is the number of bytes actually read or written, or -1 on failure. If
it returns -1, the error code is expected to be set to</p>
<p>Every buffer in <ttclass="docutils literal">bufs</tt> can be assumed to be page aligned and be of a page aligned size,
except for the last buffer of the torrent. The allocated buffer can be assumed to fit a
fully page aligned number of bytes though. This is useful when reading and writing the
last piece of a file in unbuffered mode.</p>
<p>The <ttclass="docutils literal">offset</tt> is aligned to 16 kiB boundries <em>most of the time</em>, but there are rare
exceptions when it's not. Specifically if the read cache is disabled/or full and a
client requests unaligned data, or the file itself is not aligned in the torrent.
<p>returns the currently set error code and file path associated with it,
if set.</p>
<aname="clear_error()"></a></div>
<divclass="section"id="clear-error">
<h2>clear_error()</h2>
<preclass="literal-block">
virtual void <strong>clear_error</strong> ();
</pre>
<p>reset the error state to allow continuing reading and writing
to the storage</p>
<aname="default_storage"></a></div>
</div>
<divclass="section"id="default-storage">
<h1>default_storage</h1>
<p>Declared in "<aclass="reference external"href="../include/libtorrent/storage.hpp">libtorrent/storage.hpp</a>"</p>
<p>The default implementation of <aclass="reference external"href="reference-Custom_Storage.html#storage_interface">storage_interface</a>. Behaves as a normal bittorrent client.
It is possible to derive from this class in order to override some of its behavior, when
implementing a custom storage.</p>
<preclass="literal-block">
class default_storage : public storage_interface, boost::noncopyable
int <strong>write</strong> (char const* buf, int slot, int offset, int size);
int <strong>writev</strong> (<aclass="reference external"href="file::iovec_t">file::iovec_t</a> const* buf, int slot, int offset, int num_bufs, int flags = <aclass="reference external"href="file::random_access">file::random_access</a>);
size_type <strong>physical_offset</strong> (int slot, int offset);
int <strong>readv</strong> (<aclass="reference external"href="file::iovec_t">file::iovec_t</a> const* bufs, int slot, int offset, int num_bufs, int flags = <aclass="reference external"href="file::random_access">file::random_access</a>);
bool <strong>swap_slots3</strong> (int slot1, int slot2, int slot3);
