@@ -158,7 +158,7 @@ type Constraint = (Cond, DepSet)
158158--
159159-- Typical numbers from the current version of Blodwen:
160160-- * 56 iterations until fixpoint
161−-- * out of 20k constraints total, 5-200 are relevant per iteration
161+-- * out of 20k constraints total, 5-1000 are relevant per iteration
162162minimalUsage :: Deps -> (Deps, (Set Name, UseMap))
163163minimalUsage deps
164164 = fromNumbered *** gather
@@ -166,6 +166,8 @@ minimalUsage deps
166166 where
167167 numbered = toNumbered deps
168168
169+ -- The initial solution. Consists of nodes that are
170+ -- reachable immediately, without any preconditions.
169171 seedDeps :: DepSet
170172 seedDeps = M.unionsWith S.union [ds | (cond, ds) <- IM.elems numbered, S.null cond]
171173
@@ -177,6 +179,8 @@ minimalUsage deps
177179 where
178180 addConstraint (ns, vs) = M.insertWith (M.unionWith S.union) ns vs
179181
182+ -- Build an index that maps every node to the set of constraints
183+ -- where the node appears among the preconditions.
180184 index :: IntMap Constraint -> Map Node IntSet
181185 index = IM.foldrWithKey (
182186 -- for each clause (i. ns --> _ds)
@@ -186,6 +190,9 @@ minimalUsage deps
186190 ) ix (S.toList ns)
187191 ) M.empty
188192
193+ -- Convert a solution of constraints into:
194+ -- 1. the list of names used in the program
195+ -- 2. the list of arguments used, together with their reasons
189196 gather :: DepSet -> (Set Name, UseMap)
190197 gather = foldr ins (S.empty, M.empty) . M.toList
191198 where
@@ -193,16 +200,25 @@ minimalUsage deps
193200 ins ((n, Result), rs) (ns, umap) = (S.insert n ns, umap)
194201 ins ((n, Arg i ), rs) (ns, umap) = (ns, M.insertWith (IM.unionWith S.union) n (IM.singleton i rs) umap)
195202
203+-- | In each iteration, we find the set of nodes immediately reachable
204+-- from the current set of constraints, and then reduce the set of constraints
205+-- based on that knowledge.
206+--
207+-- In the implementation, this is phase-shifted. We first reduce the set
208+-- of constraints, given the newly reachable nodes from the previous iteration,
209+-- and then compute the set of currently reachable nodes.
196210forwardChain
197− :: Map Node IntSet
198− -> DepSet
199− -> DepSet
200− -> IntMap Constraint
211+ :: Map Node IntSet -- ^ node index
212+ -> DepSet -- ^ all reachable nodes found so far
213+ -> DepSet -- ^ nodes reached in the previous iteration
214+ -> IntMap Constraint -- ^ numbered constraints
201215 -> (IntMap Constraint, DepSet)
202216forwardChain index solution previouslyNew constrs
217+ -- no newly reachable nodes, fixed point has been reached
203218 | M.null currentlyNew
204219 = (constrs, solution)
205220
221+ -- some newly reachable nodes, iterate more
206222 | otherwise
207223 = forwardChain index
208224 (M.unionWith S.union solution currentlyNew)
@@ -226,25 +242,38 @@ forwardChain index solution previouslyNew constrs
226242 (M.empty, constrs)
227243 affectedIxs
228244
245+ -- Update the pair (newly reached nodes, numbered constraint set)
246+ -- by reducing the constraint with the given number.
229247 reduceConstraint
230− :: Set Node
231− -> Int
248+ :: Set Node -- ^ nodes reached in the previous iteration
249+ -> Int -- ^ constraint number
232250 -> (DepSet, IntMap (Cond, DepSet))
233251 -> (DepSet, IntMap (Cond, DepSet))
234− reduceConstraint previouslyNew i (news, clauses)
235− | Just (cond, deps) <- IM.lookup i clauses
252+ reduceConstraint previouslyNew i (news, constrs)
253+ | Just (cond, deps) <- IM.lookup i constrs
236254 = case cond S.\\ previouslyNew of
237255 cond'
256+ -- This constraint's set of preconditions has shrunk
257+ -- to the empty set. We can add its RHS to the set of newly
258+ -- reached nodes, and remove the constraint altogether.
238259 | S.null cond'
239− -> (M.unionWith S.union news deps, IM.delete i clauses)
260+ -> (M.unionWith S.union news deps, IM.delete i constrs)
240261
262+ -- This constraint's set of preconditions has shrunk
263+ -- so we need to overwrite the numbered slot
264+ -- with the updated constraint.
241265 | S.size cond' < S.size cond
242− -> (news, IM.insert i (cond', deps) clauses)
266+ -> (news, IM.insert i (cond', deps) constrs)
243267
268+ -- This constraint's set of preconditions hasn't changed
269+ -- so we do not do anything about it.
244270 | otherwise
245− -> (news, clauses)
271+ -> (news, constrs)
246272
247− | otherwise = (news, clauses)
273+ -- Constraint number present in index but not found
274+ -- among the constraints. This happens more and more frequently
275+ -- as we delete constraints from the set.
276+ | otherwise = (news, constrs)
248277
249278-- | Build the dependency graph, starting the depth-first search from
250279-- a list of Names.