added support for explicitly flushing the disk cache

ChangeLog

@@ -10,6 +10,7 @@
 
 0.15 release
 
+	* added support for explicitly flushing the disk cache
 	* added torrent priority to affect bandwidth allocation for its peers
 	* reduced the number of floating point operations (to better support
 	  systems without FPU)

docs/manual.rst

@@ -1966,6 +1966,8 @@ Its declaration looks like this::
 		void clear_error() const;
 		void set_upload_mode(bool m) const;
 
+		void flush_cache() const;
+
 		void resolve_countries(bool r);
 		bool resolve_countries() const;
 
@@ -2409,6 +2411,21 @@ is not running because the session is paused, this still returns false. To know
 torrent is active or not, you need to inspect both ``torrent_handle::is_paused()``
 and ``session::is_paused()``.
 
+flush_cache()
+-------------
+
+	::
+
+		void flush_cache() const;
+
+Instructs libtorrent to flush all the disk caches for this torrent and close all
+file handles. This is done asynchronously and you will be notified that it's complete
+through cache_flushed_alert_.
+
+Note that by the time you get the alert, libtorrent may have cached more data for the
+torrent, but you are guaranteed that whatever cached data libtorrent had by the time
+you called ``torrent_handle::flush_cache()`` has been written to disk.
+
 force_recheck()
 ---------------
 
@@ -5698,6 +5715,20 @@ were collected. This is typically just above 1000, but if CPU is
 limited, it may be higher than that.
 
 
+cache_flushed_alert
+-------------------
+
+This alert is posted when the disk cache has been flushed for a specific torrent
+as a result of a call to `flush_cache_()`_. This alert belongs to the
+``storage_notification`` category, which must be enabled to let this alert through.
+
+::
+
+	struct flush_cached_alert: torrent_alert
+	{
+		// ...
+	};
+
 dht_announce_alert
 ------------------
 

include/libtorrent/alert_types.hpp

@@ -1118,6 +1118,14 @@ namespace libtorrent
 		int interval;
 	};
 
+	struct TORRENT_EXPORT cache_flushed_alert: torrent_alert
+	{
+		cache_flushed_alert(torrent_handle const& h);
+
+		TORRENT_DEFINE_ALERT(cache_flushed_alert);
+
+		const static int static_category = alert::storage_notification;
+	};
 }
 
 

include/libtorrent/torrent.hpp

@@ -231,6 +231,8 @@ namespace libtorrent
 		void clear_error();
 		void set_error(error_code const& ec, std::string const& file);
 		bool has_error() const { return m_error; }
+
+		void flush_cache();
 		void pause();
 		void resume();
 
@@ -724,6 +726,7 @@ namespace libtorrent
 		void on_storage_moved(int ret, disk_io_job const& j);
 		void on_save_resume_data(int ret, disk_io_job const& j);
 		void on_file_renamed(int ret, disk_io_job const& j);
+		void on_cache_flushed(int ret, disk_io_job const& j);
 
 		void on_piece_verified(int ret, disk_io_job const& j
 			, boost::function<void(int)> f);

include/libtorrent/torrent_handle.hpp

@@ -444,6 +444,7 @@ namespace libtorrent
 		void pause() const;
 		void resume() const;
 		void set_upload_mode(bool b) const;
+		void flush_cache() const;
 
 		void force_recheck() const;
 		void save_resume_data() const;

src/alert.cpp

@@ -461,5 +461,7 @@ namespace libtorrent {
 		return msg;
 	}
 
+	cache_flushed_alert::cache_flushed_alert(torrent_handle const& h): torrent_alert(h) {}
+
 } // namespace libtorrent
 

src/torrent.cpp

@@ -5054,6 +5054,18 @@ namespace libtorrent
 			&& !m_abort;
 	}
 
+	void torrent::flush_cache()
+	{
+		m_storage->async_release_files(
+			bind(&torrent::on_cache_flushed, shared_from_this(), _1, _2));
+	}
+
+	void torrent::on_cache_flushed(int ret, disk_io_job const& j)
+	{
+		if (alerts().should_post<cache_flushed_alert>())
+			alerts().post_alert(cache_flushed_alert(get_handle()));
+	}
+
 	bool torrent::is_paused() const
 	{
 		return m_paused || m_ses.is_paused();

src/torrent_handle.cpp

@@ -292,6 +292,12 @@ namespace libtorrent
 		TORRENT_FORWARD(set_upload_mode(b));
 	}
 
+	void torrent_handle::flush_cache() const
+	{
+		INVARIANT_CHECK;
+		TORRENT_FORWARD(flush_cache());
+	}
+
 	void torrent_handle::save_resume_data() const
 	{
 		INVARIANT_CHECK;