merged RC_1_1 into RC_1_2

bindings/python/src/session.cpp

@@ -22,6 +22,7 @@
 #include <libtorrent/session_stats.hpp>
 #include <libtorrent/session_status.hpp>
 #include <libtorrent/peer_class_type_filter.hpp>
+#include <libtorrent/torrent_status.hpp>
 
 #include <libtorrent/extensions/smart_ban.hpp>
 #include <libtorrent/extensions/ut_metadata.hpp>
@@ -421,17 +422,49 @@ namespace
 
     list get_torrents(lt::session& s)
     {
-        list ret;
         std::vector<torrent_handle> torrents;
         {
            allow_threading_guard guard;
            torrents = s.get_torrents();
         }
 
+        list ret;
         for (std::vector<torrent_handle>::iterator i = torrents.begin(); i != torrents.end(); ++i)
-        {
             ret.append(*i);
+        return ret;
     }
+
+    bool wrap_pred(object pred, torrent_status const& st)
+    {
+        return pred(st);
+    }
+
+    list get_torrent_status(lt::session& s, object pred, int const flags)
+    {
+        std::vector<torrent_status> torrents
+            = s.get_torrent_status(boost::bind(&wrap_pred, pred, _1), status_flags_t(flags));
+
+        list ret;
+        for (std::vector<torrent_status>::iterator i = torrents.begin(); i != torrents.end(); ++i)
+            ret.append(*i);
+        return ret;
+    }
+
+    list refresh_torrent_status(lt::session& s, list in_torrents, int const flags)
+    {
+        std::vector<torrent_status> torrents;
+        int const n = int(boost::python::len(in_torrents));
+        for (int i = 0; i < n; ++i)
+           torrents.push_back(extract<torrent_status>(in_torrents[i]));
+
+        {
+           allow_threading_guard guard;
+           s.refresh_torrent_status(&torrents, status_flags_t(flags));
+        }
+
+        list ret;
+        for (std::vector<torrent_status>::iterator i = torrents.begin(); i != torrents.end(); ++i)
+            ret.append(*i);
         return ret;
     }
 
@@ -1022,6 +1055,8 @@ void bind_session()
         .def("get_ip_filter", allow_threads(&lt::session::get_ip_filter))
         .def("find_torrent", allow_threads(&lt::session::find_torrent))
         .def("get_torrents", &get_torrents)
+        .def("get_torrent_status", &get_torrent_status, (arg("session"), arg("pred"), arg("flags") = 0))
+        .def("refresh_torrent_status", &refresh_torrent_status, (arg("session"), arg("torrents"), arg("flags") = 0))
         .def("pause", allow_threads(&lt::session::pause))
         .def("resume", allow_threads(&lt::session::resume))
         .def("is_paused", allow_threads(&lt::session::is_paused))

docs/tuning.rst

@@ -320,34 +320,21 @@ scalability
 
 In order to make more efficient use of the libtorrent interface when running a large
 number of torrents simultaneously, one can use the ``session::get_torrent_status()`` call
-together with ``session::refresh_torrent_status()``. Keep in mind that every call into
+together with ``session::post_torrent_updates()``. Keep in mind that every call into
 libtorrent that return some value have to block your thread while posting a message to
-the main network thread and then wait for a response (calls that don't return any data
+the main network thread and then wait for a response. Calls that don't return any data
-will simply post the message and then immediately return). The time this takes might
+will simply post the message and then immediately return, performing the work
-become significant once you reach a few hundred torrents (depending on how many calls
+asynchronously. The time this takes might become significant once you reach a
-you make to each torrent and how often). ``get_torrent_status`` lets you query the
+few hundred torrents, depending on how many calls you make to each torrent and how often.
-status of all torrents in a single call. This will actually loop through all torrents
+``session::get_torrent_status()`` lets you query the status of all torrents in a single call.
-and run a provided predicate function to determine whether or not to include it in
+This will actually loop through all torrents and run a provided predicate function to
-the returned vector. If you have a lot of torrents, you might want to update the status
+determine whether or not to include it in the returned vector.
-of only certain torrents. For instance, you might only be interested in torrents that
-are being downloaded.
 
-The intended use of these functions is to start off by calling ``get_torrent_status()``
+To use ``session::post_torrent_updates()`` torrents need to have the ``flag_update_subscribe``
-to get a list of all torrents that match your criteria. Then call ``refresh_torrent_status()``
+flag set. When post_torrent_updates() is called, a ``state_update_alert`` alert
-on that list. This will only refresh the status for the torrents in your list, and thus
+is posted, with all the torrents that have updated since the last time this
-ignore all other torrents you might be running. This may save a significant amount of
+function was called. The client have to keep its own state of all torrents, and
-time, especially if the number of torrents you're interested in is small. In order to
+update it based on this alert.
-keep your list of interested torrents up to date, you can either call ``get_torrent_status()``
-from time to time, to include torrents you might have become interested in since the last
-time. In order to stop refreshing a certain torrent, simply remove it from the list.
-
-A more efficient way however, would be to subscribe to status alert notifications, and
-update your list based on these alerts. There are alerts for when torrents are added, removed,
-paused, resumed, completed etc. Doing this ensures that you only query status for the
-minimal set of torrents you are actually interested in.
-
-To get an update with only the torrents that have changed since last time, call
-``session::post_torrent_updates()``.
 
 benchmarking
 ============

include/libtorrent/session_handle.hpp

@@ -147,6 +147,18 @@ namespace libtorrent {
 		//
 		// Any torrent_status object whose ``handle`` member is not referring to
 		// a valid torrent are ignored.
+		//
+		// The intended use of these functions is to start off by calling
+		// ``get_torrent_status()`` to get a list of all torrents that match your
+		// criteria. Then call ``refresh_torrent_status()`` on that list. This
+		// will only refresh the status for the torrents in your list, and thus
+		// ignore all other torrents you might be running. This may save a
+		// significant amount of time, especially if the number of torrents you're
+		// interested in is small. In order to keep your list of interested
+		// torrents up to date, you can either call ``get_torrent_status()`` from
+		// time to time, to include torrents you might have become interested in
+		// since the last time. In order to stop refreshing a certain torrent,
+		// simply remove it from the list.
 		std::vector<torrent_status> get_torrent_status(
 			std::function<bool(torrent_status const&)> const& pred
 			, status_flags_t flags = {}) const;