---

yaml
---
r: 273151
b: refs/heads/beta
c: c1df41e
h: refs/heads/master
i:
  273149: bc41291
  273147: 176cccd
  273143: 4e21196
  273135: d67c8f6
  273119: 574c651
  273087: ae15197
  273023: 7395535
  272895: 0f5cbc5

Author: aturon

[refs]

@@ -23,7 +23,7 @@ refs/tags/0.9: 36870b185fc5f5486636d4515f0e22677493f225
 refs/tags/0.10: ac33f2b15782272ae348dbd7b14b8257b2148b5a
 refs/tags/0.11.0: e1247cb1d0d681be034adb4b558b5a0c0d5720f9
 refs/tags/0.12.0: f0c419429ef30723ceaf6b42f9b5a2aeb5d2e2d1
-refs/heads/beta: ed8d059d8d49491b736ea88edd8f2b57a866c44a
+refs/heads/beta: c1df41e776c5a65ce8345d34a7e22296a99abd5e
 refs/tags/1.0.0-alpha: e42bd6d93a1d3433c486200587f8f9e12590a4d7
 refs/heads/tmp: e06d2ad9fcd5027bcaac5b08fc9aa39a49d0ecd3
 refs/tags/1.0.0-alpha.2: 4c705f6bc559886632d3871b04f58aab093bfa2f

branches/beta/src/librustc/middle/traits/README.md

@@ -428,3 +428,43 @@ We used to try and draw finer-grained distinctions, but that led to a
 serious of annoying and weird bugs like #22019 and #18290. This simple
 rule seems to be pretty clearly safe and also still retains a very
 high hit rate (~95% when compiling rustc).
+
+# Specialization
+
+Defined in the `specialize` module.
+
+The basic strategy is to build up a *specialization graph* during
+coherence checking. Insertion into the graph locates the right place
+to put an impl in the specialization hierarchy; if there is no right
+place (due to partial overlap but no containment), you get an overlap
+error. Specialization is consulted when selecting an impl (of course),
+and the graph is consulted when propagating defaults down the
+specialization hierarchy.
+
+You might expect that the specialization graph would be used during
+selection -- i.e., when actually performing specialization. This is
+not done for two reasons:
+
+- It's merely an optimization: given a set of candidates that apply,
+  we can determine the most specialized one by comparing them directly
+  for specialization, rather than consulting the graph. Given that we
+  also cache the results of selection, the benefit of this
+  optimization is questionable.
+
+- To build the specialization graph in the first place, we need to use
+  selection (because we need to determine whether one impl specializes
+  another). Dealing with this reentrancy would require some additional
+  mode switch for selection. Given that there seems to be no strong
+  reason to use the graph anyway, we stick with a simpler approach in
+  selection, and use the graph only for propagating default
+  implementations.
+
+Trait impl selection can succeed even when multiple impls can apply,
+as long as they are part of the same specialization family. In that
+case, it returns a *single* impl on success -- this is the most
+specialized impl *known* to apply. However, if there are any inference
+variables in play, the returned impl may not be the actual impl we
+will use at trans time. Thus, we take special care to avoid projecting
+associated types unless either (1) the associated type does not use
+`default` and thus cannot be overridden or (2) all input types are
+known concretely.

branches/beta/src/librustc/middle/traits/specialize.rs

@@ -13,6 +13,9 @@
 //
 // At the moment, this implementation support only the simple "chain" rule:
 // If any two impls overlap, one must be a strict subset of the other.
+//
+// See traits/README.md for a bit more detail on how specialization
+// fits together with the rest of the trait machinery.
 
 use super::util;
 use super::SelectionContext;