[m-rev.] diff: simplify and document deep_profiler/exclude.m

[Zoltan Somogyi]

deep_profiler/exclude.m:
	Simplify and document this module.

deep_profiler/query.m:
	Minor update to conform to a simplification in the interface of
	exclude.m.

Zoltan.

cvs diff: Diffing .
Index: exclude.m
===================================================================
RCS file: /home/mercury1/repository/mercury/deep_profiler/exclude.m,v
retrieving revision 1.1
diff -u -b -r1.1 exclude.m
--- exclude.m	2001/07/03 08:16:17	1.1
+++ exclude.m	2001/07/12 16:09:13
@@ -6,36 +6,73 @@
 %
 % Author: zs.
 %
-% XXX
+% This module handles contour exclusion.
+%
+% When asking for the list of callers of a procedure, the user may ask for
+% contour exclusion to be applied. This means that instead of deriving the
+% displayed information from the immediate callers of the specified procedure,
+% the system uses the nearest ancestors of the specified procedure that are not
+% excluded. Contour exclusion draws a line through the program, with the
+% excluded procedures below the line and the non-excluded procedures above;
+% and when looking at the callers of a procedure, the system uses the nearest
+% ancestor that is above the line.
+% 
+% The read_exclude_file procedure reads in the file that specifies the set of
+% excluded procedures. The exclusion file should consist of a sequence of
+% lines, and each line should contain two words. The first word should be
+% either "all" or "internal"; the second should the name of a module.
+% If the first word is "all", then all procedures in the named module are
+% excluded; if the first word is "internal", then all internal (non-exported)
+% procedures in the named module are excluded. The first argument of
+% read_exclude_file specifies the name of the exclusion file; the second is the
+% main profiler data structure, which read_exclude_file uses to verify the
+% existence of the named modules. Read_exclude_file returns an abstract data
+% structure representing the contents of the file, provided that the file
+% exists and has the proper structure.
+%
+% The only thing the caller can do with that abstract data structure is give it
+% back to apply_contour_exclusion. This predicate applies contour exclusion by
+% following the ancestors of the supplied call_site_dynamic_ptr until it
+% arrives at a procedure which is not excluded.
 
 :- module exclude.
 
 :- interface.
 
 :- import_module profile.
-:- import_module std_util, io, set.
+:- import_module std_util, io.
 
-:- type exclude_spec
-	--->	all_procedures(string)		% Exclude all procedures in the
-						% named module.
-	;	internal_procedures(string).	% Exclude all procedures in the 
-						% named module, except those
-						% which are exported from the
-						% module.
-					
+:- type exclude_file.
 
-:- pred read_exclude_file(string::in, deep::in,
-	maybe_error(set(exclude_spec))::out,
+:- pred read_exclude_file(string::in, deep::in, maybe_error(exclude_file)::out,
 	io__state::di, io__state::uo) is det.
 
-:- func apply_contour_exclusion(deep, set(exclude_spec), call_site_dynamic_ptr)
+:- func apply_contour_exclusion(deep, exclude_file, call_site_dynamic_ptr)
 	= call_site_dynamic_ptr.
 
 %-----------------------------------------------------------------------------%
 
 :- implementation.
+
+:- import_module bool, char, string, list, set, map, require.
+
+:- type exclude_file == set(exclude_spec).
+
+:- type exclude_spec
+	--->	exclude_spec(
+			string,		% the name of a module
+			exclusion_type	% which procedures in the module
+					% are excluded
+		).
+
+:- type exclusion_type
+	--->	all_procedures		% Exclude all procedures in the
+					% named module.
+	;	internal_procedures.	% Exclude all procedures in the 
+					% named module, except those
+					% which are exported from the
+					% module.
 
-:- import_module bool, char, string, list, map, require.
 
 read_exclude_file(FileName, Deep, Res) -->
 	io__open_input(FileName, Res0),
@@ -74,12 +111,13 @@
 			{ Words = [Scope, ModuleName] },
 			{
 				Scope = "all",
-				Spec = all_procedures(ModuleName)
+				ExclType = all_procedures
 			;
 				Scope = "internal",
-				Spec = internal_procedures(ModuleName)
+				ExclType = internal_procedures
 			}
 		->
+			{ Spec = exclude_spec(ModuleName, ExclType) },
 			{ RevSpecs1 = [Spec | RevSpecs0] },
 			read_exclude_lines(FileName, InputStream, RevSpecs1,
 				Res)
@@ -123,12 +161,11 @@
 
 :- func spec_to_module_name(exclude_spec) = string.
 
-spec_to_module_name(all_procedures(ModuleName)) = ModuleName.
-spec_to_module_name(internal_procedures(ModuleName)) = ModuleName.
+spec_to_module_name(exclude_spec(ModuleName, _)) = ModuleName.
 
 %-----------------------------------------------------------------------------%
 
-apply_contour_exclusion(Deep, ExcludedSpec, CSDPtr0) = CSDPtr :-
+apply_contour_exclusion(Deep, ExcludedSpecs, CSDPtr0) = CSDPtr :-
 	( valid_call_site_dynamic_ptr(Deep, CSDPtr0) ->
 		deep_lookup_call_site_dynamics(Deep, CSDPtr0, CSD),
 		PDPtr = CSD ^ csd_caller,
@@ -137,23 +174,19 @@
 		deep_lookup_proc_statics(Deep, PSPtr, PS),
 		ModuleName = PS ^ ps_decl_module,
 		(
-			set__member(all_procedures(ModuleName),
-				ExcludedSpec)
-		->
-			deep_lookup_clique_index(Deep, PDPtr, CliquePtr),
-			deep_lookup_clique_parents(Deep, CliquePtr,
-				EntryCSDPtr),
-			CSDPtr = apply_contour_exclusion(Deep, ExcludedSpec,
-				EntryCSDPtr)
+			set__member(ExclSpec, ExcludedSpecs),
+			ExclSpec = exclude_spec(ModuleName, ExclType),
+			(
+				ExclType = all_procedures
 		;
-			set__member(internal_procedures(ModuleName),
-				ExcludedSpec),
+				ExclType = internal_procedures,
 			PS ^ ps_in_interface = no
+			)
 		->
 			deep_lookup_clique_index(Deep, PDPtr, CliquePtr),
 			deep_lookup_clique_parents(Deep, CliquePtr,
 				EntryCSDPtr),
-			CSDPtr = apply_contour_exclusion(Deep, ExcludedSpec,
+			CSDPtr = apply_contour_exclusion(Deep, ExcludedSpecs,
 				EntryCSDPtr)
 		;
 			CSDPtr = CSDPtr0
@@ -161,4 +194,3 @@
 	;
 		CSDPtr = CSDPtr0
 	).
-
Index: query.m
===================================================================
RCS file: /home/mercury1/repository/mercury/deep_profiler/query.m,v
retrieving revision 1.1
diff -u -b -r1.1 query.m
--- query.m	2001/07/03 08:16:18	1.1
+++ query.m	2001/07/12 15:17:53
@@ -1786,7 +1786,7 @@
 
 pair_self(CSDPtr) = CSDPtr - CSDPtr.
 
-:- func pair_contour(deep, set(exclude_spec), call_site_dynamic_ptr)
+:- func pair_contour(deep, exclude_file, call_site_dynamic_ptr)
 	= pair(call_site_dynamic_ptr).
 
 pair_contour(Deep, ExcludeSpec, CSDPtr) =
cvs diff: Diffing notes
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------