diff --git a/Jamfile b/Jamfile index b75598b44..b2031a51f 100755 --- a/Jamfile +++ b/Jamfile @@ -244,6 +244,7 @@ SOURCES = alert assert connection_queue + disk_buffer_holder entry escape_string gzip diff --git a/docs/building.html b/docs/building.html index 68d6a9613..f430b09b1 100644 --- a/docs/building.html +++ b/docs/building.html @@ -285,6 +285,16 @@ used. +
Contents
libtorrent has a plugin interface for implementing extensions to the protocol. @@ -47,13 +48,13 @@ to fit a particular (closed) network.
In short, the plugin interface makes it possible to:
Writing your own plugin is a very easy way to introduce serious bugs such as dead locks and race conditions. Since a plugin has access to internal structures it is also quite easy to sabotage libtorrent's operation.
@@ -64,12 +65,12 @@ thread, you cannot use any of the member functions on the internal structures in libtorrent, since those require the mutex to be locked. Futhermore, you would also need to have a mutex on your own shared data within the plugin, to make sure it is not accessed at the same time from the libtorrent thread (through a -callback). See boost thread's mutex. If you need to send out a message from +callback). See boost thread's mutex. If you need to send out a message from another thread, use an internal queue, and do the actual sending in tick().The plugin interface consists of two base classes that the plugin may implement. These are called torrent_plugin and peer_plugin. They are both found in the <libtorrent/extensions.hpp> header.
@@ -92,8 +93,8 @@ for this torrent. If it is a valid pointer (to a class inheriting torrent_plugin), it will be associated with this torrent and callbacks will be made on torrent events.The synopsis for torrent_plugin follows:
struct torrent_plugin @@ -115,8 +116,8 @@ struct torrent_pluginThis is the base class for a torrent_plugin. Your derived class is (if added as an extension) instantiated for each torrent in the session. The callback hook functions are defined as follows.
--new_connection()
++-new_connection()
boost::shared_ptr<peer_plugin> new_connection(peer_connection*);@@ -133,8 +134,8 @@ held by the torrent object. So, it is generally a good idea to not keep a use weak_ptr.If this function throws an exception, the connection will be closed.
-on_piece_pass() on_piece_fail()
++-on_piece_pass() on_piece_fail()
void on_piece_pass(int index); void on_piece_failed(int index); @@ -144,16 +145,16 @@ check, respectively. The indextorrent and the piece_picker.-tick()
++-tick()
void tick();This hook is called approximately once per second. It is a way of making it easy for plugins to do timed events, for sending messages or whatever.
-on_pause() on_resume()
++-on_pause() on_resume()
bool on_pause(); bool on_resume(); @@ -169,8 +170,8 @@ handler it will recurse back into your handler, so in order to invoke the standard handler, you have to keep your own state on whether you want standard behavior or overridden behavior.--on_files_checked()
++on_files_checked()
void on_files_checked();@@ -180,8 +181,8 @@ checked. If there are no files to check, this function is called immediately.-peer_plugin
+++peer_plugin
struct peer_plugin { @@ -201,7 +202,7 @@ struct peer_plugin virtual bool on_have_none(); virtual bool on_allowed_fast(int index); virtual bool on_request(peer_request const& req); - virtual bool on_piece(peer_request const& piece, char const* data); + virtual bool on_piece(peer_request const& piece, disk_buffer_holder& buffer); virtual bool on_cancel(peer_request const& req); virtual bool on_reject(peer_request const& req); virtual bool on_suggest(int index); @@ -218,6 +219,24 @@ struct peer_plugin };+disk_buffer_holder
++struct disk_buffer_holder +{ + disk_buffer_holder(aux::session_impl& s, char* b); + ~disk_buffer_holder(); + char* release(); + char* buffer(); +}; ++The disk buffer holder acts like a scoped_ptr that frees a disk buffer +when it's destructed, unless it's released. release returns the disk +buffer and transferres ownership and responsibility to free it to the caller.
+A disk buffer is freed by passing it to session_impl::free_disk_buffer().
+buffer() returns the pointer without transferring responsibility. If +this buffer has been released, buffer() will return 0.
+