chiark / gitweb /
notation: strip word "merge" from \setmergeof etc.; use new definition of \commitmerg...
[topbloke-formulae.git] / ranking.tex
1 \section{Ranking phase}
2
3 We run the following algorithm:
4 \begin{enumerate}
5 \item Set $\allpatches = \{ \}$.
6 \item Repeatedly:
7 \begin{enumerate}
8 \item Clear out the graph $\hasdirdep$ so it has no edges.
9 \item Execute $\alg{Rank-Recurse}(\pc_0)$
10 \item Until $\allpatches$ remains unchanged.
11 \end{enumerate}
12 \end{enumerate}
13
14 $\alg{Rank-Recurse}(\pc)$ is:
15 \begin{enumerate}
16
17 \item If we have already done $\alg{Rank-Recurse}(\pc)$ in this
18 ranking iteration, do nothing.  Otherwise:
19
20 \item Add $\pc$ to $\allpatches$ if it is not there already.
21 If it was added, recalculate $\allsrcs$ accordingly.
22
23 \item Set
24 $$
25   \set S \iassign h(\pcn)
26      \cup
27          \{ \baseof{E} \; | \; E \in \pendsof{\allsrcs}{\pcy} \}
28 $$
29
30 and $W \iassign w(h(\pcn))$
31
32 \item While $\exists_{S \in \set S} S \ge W$,
33 update $W \assign S$ and $\set S \assign \set S \, \backslash \{ S \}$
34
35 (This will often remove $W$ from $\set S$.  Afterwards, $\set S$
36 is a collection of heads to be merged into $W$.)
37
38 \item Choose an ordering of $\set S$, $S_i$ for $i=1 \ldots n$.
39
40 \item For each $S_i$ in turn, choose a corresponding $M_i$
41 such that $$
42    M_i \le S_i \land \left[
43    M_i \le W \lor \bigexists_{j<i} M_i \le S_j
44    \right]
45 $$
46
47 \item Set $\Gamma \iassign \depsreqof{W}$.
48
49 If there are multiple candidates we prefer $M_i \in \pcn$
50 if available.
51
52 \item For each $i \ldots 1..n$, update our putative direct
53 dependencies:
54 $$
55 \Gamma \assign \setmergeof{
56     \Gamma
57   }{
58     \begin{cases}
59      M_i \in \pcn :     & \depsreqof{M_i} \\
60      M_i \not\in \pcn : & \{ \}
61     \end{cases}
62   }{
63     \depsreqof{S_i}
64   }
65 $$
66
67 TODO define $\setmerge$
68
69 \item Finalise our putative direct dependencies
70 $
71 \Gamma \assign g(\pc, \Gamma)
72 $
73
74 \item For each direct dependency $\pd \in \Gamma$,
75
76 \begin{enumerate}
77 \item Add an edge $\pc \hasdirdep \pd$ to the digraph (adding nodes
78 as necessary).
79 If this results in a cycle, abort entirely (as the function $g$ is
80 inappropriate; a different $g$ could work).
81 \item Run $\alg{Rank-Recurse}(\pd)$.
82 \end{enumerate}
83
84 \end{enumerate}
85
86 \subsection{Results of the ranking phase}
87
88 By the end of the ranking phase, we have recorded the following
89 information:
90
91 \begin{itemize}
92 \item
93 $ \allpatches, \hasdirdep $ and hence the completion of $\hasdirdep$
94 into the partial order $\hasdep$.
95
96 \item
97 For each $\pc \in \allpatches$,
98 the base branch starting point commit $W^{\pcn} = W$.
99
100 \item
101 For each $\pc$,
102 the direct dependencies $\Gamma^{\pc} = \Gamma$.
103
104 \item
105 For each $\pc$,
106 the ordered set of base branch sources $\set S^{\pcn} = \set S,
107 S^{\pcn}_i = S_i$
108 and corresponding merge bases $M^{\pcn}_i = M_i$.
109
110 \end{itemize}
111
112 \subsection{Proof of termination}
113
114 $\alg{Rank-Recurse}(\pc)$ recurses but only downwards through the
115 finite graph $\hasdirdep$, so it must terminate.  
116
117 The whole ranking algorithm iterates but each iteration involves
118 adding one or more patches to $\allpatches$.  Since there are
119 finitely many patches and we never remove anything from $\allpatches$
120 this must complete eventually.
121
122 $\qed$
123