improve documentation on peer classes

docs/manual.rst

@@ -815,6 +815,64 @@ Custom peer classes can be assigned to torrents, with the ??? call, in which
 case all its peers will belong to the class. They can also be assigned based on
 the peer's IP address. See set_peer_class_filter() for more information.
 
+peer class examples
+-------------------
+
+Here are a few examples of common peer class operations.
+
+To make the global rate limit apply to local peers as well, update the IP-filter
+based peer class assignment:
+
+.. code:: c++
+
+		std::uint32_t const mask = 1 << lt::session::global_peer_class_id;
+		ip_filter f;
+
+		// for every IPv4 address, assign the global peer class
+		f.add_rule(address_v4::from_string("0.0.0.0")
+			, address_v4::from_string("255.255.255.255")
+			, mask);
+
+		// for every IPv6 address, assign the global peer class
+		f.add_rule(address_v6::from_string("::")
+			, address_v6::from_string("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")
+			, mask);
+		ses.set_peer_class_filter(f);
+
+To make uTP sockets exempt from rate limiting:
+
+.. code:: c++
+
+	peer_class_type_filter flt;
+	// filter out the global and local peer class for uTP sockets, if these
+	// classes are set by the IP filter
+	flt.disallow(peer_class_type_filter::utp_socket, session::global_peer_class_id);
+	flt.disallow(peer_class_type_filter::utp_socket, session::local_peer_class_id);
+
+	// this filter should not add the global or local peer class to utp sockets
+	flt.remove(peer_class_type_filter::utp_socket, session::global_peer_class_id);
+	flt.remove(peer_class_type_filter::utp_socket, session::local_peer_class_id);
+
+	ses.set_peer_class_type_filter(flt);
+
+To make all peers on the internal network unthrottled:
+
+.. code:: c++
+
+		std::uint32_t const mask = 1 << lt::session::global_peer_class_id;
+		ip_filter f;
+
+		// for every IPv4 address, assign the global peer class
+		f.add_rule(address_v4::from_string("0.0.0.0")
+			, address_v4::from_string("255.255.255.255")
+			, mask);
+
+		// for every address on the local metwork, set the mastk to 0
+		f.add_rule(address_v4::from_string("10.0.0.0")
+			, address_v4::from_string("10.255.255.255")
+			, 0);
+		ses.set_peer_class_filter(f);
+
 SSL torrents
 ============
 

examples/client_test.cpp

@@ -1553,9 +1553,8 @@ int main(int argc, char* argv[])
 	if (rate_limit_locals)
 	{
 		ip_filter pcf;
-		// 1 is the global peer class. This should be done properly in the future
 		pcf.add_rule(address_v4::from_string("0.0.0.0")
-			, address_v4::from_string("255.255.255.255"), 1);
+			, address_v4::from_string("255.255.255.255"), 1 << lt::session::global_peer_class_id);
 #if TORRENT_USE_IPV6
 		pcf.add_rule(address_v6::from_string("::")
 			, address_v6::from_string("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), 1);

include/libtorrent/add_torrent_params.hpp

@@ -406,6 +406,9 @@ namespace libtorrent
 		// 
 		// -1 means unlimited on these settings just like their counterpart
 		// functions on torrent_handle
+		// 
+		// For fine grained control over rate limits, including making them apply
+		// to local peers, see peer-classes_.
 		int max_uploads;
 		int max_connections;
 		int upload_limit;

include/libtorrent/settings_pack.hpp

@@ -1279,6 +1279,9 @@ namespace libtorrent
 			// limited.
 			// 
 			// A value of 0 means unlimited.
+			// 
+			// For fine grained control over rate limits, including making them apply
+			// to local peers, see peer-classes_.
 			upload_rate_limit,
 			download_rate_limit,
 #ifndef TORRENT_NO_DEPRECATE

include/libtorrent/torrent_handle.hpp

@@ -1119,6 +1119,8 @@ namespace libtorrent
 		// 
 		// ``upload_limit`` and ``download_limit`` will return the current limit
 		// setting, for upload and download, respectively.
+		// 
+		// Local peers are not rate limited by default. see peer-classes_.
 		void set_upload_limit(int limit) const;
 		int upload_limit() const;
 		void set_download_limit(int limit) const;