[m-rev.] [reuse] diff: document code

[Nancy Mazur]

Estimated hours taken: 1
Branches: reuse

Document/clean up (a bit) sr_top, sr_direct and sr_dead. 

sr_top: 
sr_direct:
sr_dead: 
	Document and clean up. 


Index: sr_direct.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/Attic/sr_direct.m,v
retrieving revision 1.1.2.18
diff -u -r1.1.2.18 sr_direct.m
--- sr_direct.m	2 Jun 2004 10:30:53 -0000	1.1.2.18
+++ sr_direct.m	10 Jun 2004 05:08:06 -0000
@@ -8,7 +8,9 @@
 % Main authors: nancy, petdr
 % 
 % Determine the direct reuse in one procedure.  Direct reuse consists of
-% identifying which cells die.
+% identifying the deconstructions in which cell die if the procedure is called
+% in the appropriate way. The "appropriate way" is described by a reuse
+% condition. 
 %
 %-----------------------------------------------------------------------------%
 
@@ -50,44 +52,49 @@
 :- import_module assoc_list.
 :- import_module require.
 
+	% The direct-reuse analysis consists of three steps: 
+	% 1. pre-annotations (local forward use, local backward use)
+	% 2. 'deadness' analysis, i.e. identifying where datastructures
+	% potentially die. 
+	% 3. 'choice' analysis, i.e. identify where dead datastructure can be
+	% reused. 
 process_proc(PredId, ProcId, ProcInfo0, ProcInfo, ModuleInfo0, ModuleInfo) -->
-		% Determine the LFU (local forward use)
-	globals__io_lookup_bool_option(very_verbose, VeryVerbose),
+	% Some pre-processing: 
+	% - Initialise the reuse information.
+	% - Annotate goals with local forward use (lfu).
+	% - Annotate goals with local backward use (lbu). 
+	% - Annotate the goals with their goal-paths (used to identify the
+	% unifications, later in the choice analysis)
+	% XXX these goal-paths should become the main way of identifying the
+	% places of reuse, instead of annotating the actual goals.
 	{ initialise_reuse_info(ProcInfo0, ProcInfo00) },
 	{ sr_lfu__process_proc(ProcInfo00, ProcInfo1) },
-
-		% Determine the LBU (local backward use)
 	{ sr_lbu__process_proc(ModuleInfo0, ProcInfo1, ProcInfo2b) },
-
-		% Annotate the goals with their goal-paths.
 	{ goal_path__fill_slots(ProcInfo2b, ModuleInfo0, ProcInfo2) }, 
 
-		% Determine which cells die and can be reused and what
-		% the conditions on that reuse are
+	globals__io_lookup_bool_option(very_verbose, VeryVerbose),
+
+	% After the preliminary annotations, perform the actual analysis of the
+	% procedure goal. 
+	passes_aux__write_proc_progress_message("% Analysing ", 
+			PredId, ProcId, ModuleInfo0), 
+
 	{ proc_info_goal(ProcInfo2, Goal0) },
 
-	(
-		{ VeryVerbose = yes }
-	->
-		passes_aux__write_proc_progress_message(
-			"% Analysing ", PredId, ProcId, ModuleInfo0), 
-		io__write_string("%\tdeadness analysis...")
-	; 
-		[]
-	),
+	% 'Deadness' analysis: determine the deconstructions in which data
+	% structures potentially die. 
+	passes_aux__maybe_write_string(VeryVerbose, "%\tdeadness analysis..."),
 	{ sr_dead__process_goal(PredId,ProcInfo0,ModuleInfo0,Goal0,Goal1) },
+	passes_aux__maybe_write_string(VeryVerbose, "done.\n"),
 
-	maybe_write_string(VeryVerbose, "done.\n"),
-
-		% Select which cells will be reused and which can be
-		% compile time garbage collected.
-	maybe_write_string(VeryVerbose, "%\tchoice analysis..."),
-	% sr_choice__get_strategy(Strategy, ModuleInfo0, ModuleInfo),
-	% { proc_info_vartypes(ProcInfo0, VarTypes) },
-	% { sr_choice__process_goal(Strategy, VarTypes, ModuleInfo,
-	%		ProcInfo0, Goal1, Goal, MaybeReuseConditions) },
+	% 'Choice' analysis: determine how the detected dead data structures
+	% can be reused locally. 
+	passes_aux__maybe_write_string(VeryVerbose, "%\tchoice analysis..."),
 	{ proc_info_vartypes(ProcInfo0, VarTypes) }, 
-	% { ModuleInfo = ModuleInfo0 }, 
+
+	% XXX Getting the strategy also performs the check whether the
+	% arguments given to the mmc were correct. This is definitely not the
+	% right moment to check these arguments. Should be done way earlier. 
 	sr_choice_util__get_strategy(Strategy, ModuleInfo0, ModuleInfo),
 	{ Strategy = strategy(Constraint, Selection) },
 	(
Index: sr_dead.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/Attic/sr_dead.m,v
retrieving revision 1.1.2.22
diff -u -r1.1.2.22 sr_dead.m
--- sr_dead.m	7 Jun 2004 08:14:53 -0000	1.1.2.22
+++ sr_dead.m	10 Jun 2004 05:08:07 -0000
@@ -7,10 +7,13 @@
 % Module:	sr_dead
 % Main authors: nancy
 % 
-% Mark each cell that dies with its reuse_condition, and mark each
-% construction with the cells that construction could possibly reuse.
-% sr_choice is responsible for deciding which cell will actually be
-% reused.
+% Determine the deconstructions at which the deconstructed data structure
+% may potentially die. Record these dead data structures with the conditions
+% for reusing them (i.e. the conditions in which they die). For each dead
+% data structure we also keep track of the constructions which might be
+% interested in reusing that structure. 
+% It is up to the choice analysis to make a choice between these possible
+% candidates for reuse. 
 %
 %-----------------------------------------------------------------------------%
 
@@ -118,7 +121,6 @@
 annotate_goal(ProcInfo, HLDS, Expr0 - Info0, Goal, 
 			Pool0, Pool, Alias0, Alias) :- 
 	Expr0 = disj(Goals0),
-	goal_info_get_outscope(Info0, Outscope), 
 	(
 		Goals0 = []
 	->
@@ -136,6 +138,7 @@
 			),
 			Goals0, Goals, 
 			ListPools, ListAliases),
+		goal_info_get_outscope(Info0, Outscope), 
 		dead_cell_pool_least_upper_bound_disj(Outscope,
 			ListPools, Pool),
 		pa_alias_as__least_upper_bound_list(HLDS, ProcInfo, 
@@ -144,7 +147,7 @@
 	Info = Info0,
 	Expr = disj(Goals),
 	Goal = Expr - Info. 
-	
+
 annotate_goal(ProcInfo, HLDS, Expr0 - Info0, Goal, 
 			Pool0, Pool, Alias0, Alias) :- 
 	Expr0 = not(NegatedGoal0),
Index: sr_top.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/Attic/sr_top.m,v
retrieving revision 1.1.2.1
diff -u -r1.1.2.1 sr_top.m
--- sr_top.m	2 Jun 2004 10:30:55 -0000	1.1.2.1
+++ sr_top.m	10 Jun 2004 05:08:07 -0000
@@ -19,8 +19,10 @@
 % 		H3 := H2
 % 	;
 % 			% Cell H1 dies provided some condition about the
-% 			% aliasing of H1 is true.  This is a direct
-% 			% reuse.
+% 			% aliasing of H1 is true.  A deconstruction
+% 			% generating a dead cell, followed by a
+% 			% construction reusing that cell, is called a direct
+% 			% reuse. 
 % 		H1 => [X | Xs],
 %
 % 			% If the condition about the aliasing of H1
@@ -44,9 +46,13 @@
 
 :- import_module list, io.
 
+	% Perform the structure reuse analysis. 
 :- pred structure_reuse(module_info::in, module_info::out,
 	io::di, io::uo) is det.
 
+	% Write the reuse information of a module as pragma's in the trans_opt
+	% of that module. 
+	% XXX This procedure should be defined elsewhere. 
 :- pred write_pragma_reuse_info(module_info::in, list(pred_id)::in,
 	pred_id::in, io::di, io::uo) is det.
 
@@ -82,7 +88,9 @@
 		process_unproc_reuse_pragma, UnprocReusePragmas, 
 		HLDS00, HLDS01), 
 	{ module_info_remove_unproc_reuse_pragmas(HLDS01, HLDS0) }, 
-	
+
+	% We do not want to analyse predicates that are introduced by the
+	% compiler. We will therefore filter out these predicates.
 	{ module_info_get_special_pred_map(HLDS0, SpecialPredMap) },
 	{ map__values(SpecialPredMap, SpecialPredIds) },
 

-- 
nancy.mazur at cs.kuleuven.ac.be ------------ Katholieke Universiteit Leuven -
tel: +32-16-327596 - fax: +32-16-327996 ------- Dept. of Computer Science -
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------