[m-rev.] diff: bring deep profile documentation up to date (way overdue)

[Zoltan Somogyi]

deep_profiler/*.m:
	Minor cleanups.

deep_profiler/notes/deep_profiling.html:
	Bring the documentation of the deep profiler up to date.

Zoltan.

cvs diff: Diffing .
Index: html_format.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/deep_profiler/html_format.m,v
retrieving revision 1.4
diff -u -b -r1.4 html_format.m
--- html_format.m	24 Mar 2005 01:10:27 -0000	1.4
+++ html_format.m	25 Apr 2005 07:47:29 -0000
@@ -72,7 +72,7 @@
 :- type one_two_id_line_group	== line_group(one_id, two_id_sub_lines).
 
 	% This function takes a context description (which may be empty)
-	% and a HTML string describing all fields on in row but the first,
+	% and a HTML string describing all fields in a row but the first,
 	% and returns the HTML for the full row.
 :- func add_context(string, line_group(one_id, LL)) = line_group(two_id, LL).
 
Index: mdprof_cgi.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/deep_profiler/mdprof_cgi.m,v
retrieving revision 1.9
diff -u -b -r1.9 mdprof_cgi.m
--- mdprof_cgi.m	25 Apr 2005 06:51:57 -0000	1.9
+++ mdprof_cgi.m	25 Apr 2005 07:12:14 -0000
@@ -43,7 +43,7 @@
 :- import_module string.
 
 % The web server should always set QUERY_STRING. It may also pass its contents
-% as arguments, but if any characters specials to the shell occur in the query,
+% as arguments, but if any characters special to the shell occur in the query,
 % they will screw up the argument list. We therefore look at the argument list
 % only if QUERY_STRING isn't set, which means that the program was invoked
 % from the command line for debugging.
@@ -164,7 +164,7 @@
 	).
 
 % This predicate is for debugging the command line given to mdprof_cgi by the
-% web server, should that be necessary
+% web server, should that be necessary.
 %
 % :- pred write_bracketed_string(string::in, io::di, io::uo)
 % 	is det.
@@ -306,7 +306,7 @@
 		),
 		(
 			ServerProcess = no,
-			% --no-server process should be specified only during
+			% --no-server-process should be specified only during
 			% debugging.
 			release_lock(Debug, MutexFile, !IO),
 			remove_want_file(WantFile, !IO),
@@ -338,8 +338,8 @@
 		io__format("error reading data file: %s\n", [s(Error)], !IO)
 	).
 
-% Become the new server. Delete the mutex and want files when we get out
-% of the critical region.
+	% Become the new server. Delete the mutex and want files
+	% when we get out of the critical region.
 
 :- pred start_server(option_table::in, string::in, string::in,
 	maybe(io__output_stream)::in, string::in, string::in, deep::in,
@@ -359,8 +359,7 @@
 		DetachProcess = yes,
 		detach_process(DetachRes, !IO)
 	),
-	(
-		DetachRes = in_child(ChildHasParent) ->
+	( DetachRes = in_child(ChildHasParent) ->
 		% We are in the child; start serving queries.
 		(
 			ChildHasParent = child_has_parent,
@@ -408,8 +407,7 @@
 		lookup_bool_option(Options, canonical_clique, Canonical),
 		server_loop(ToServerPipe, FromServerPipe, TimeOut,
 			MaybeDebugStream, Debug, Canonical, 0, Deep, !IO)
-	;
-		DetachRes = in_parent ->
+	; DetachRes = in_parent ->
 		% We are in the parent after we spawned the child. We cause
 		% the process to exit simply by not calling server_loop.
 		%
Index: timeout.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/deep_profiler/timeout.m,v
retrieving revision 1.11
diff -u -b -r1.11 timeout.m
--- timeout.m	24 Mar 2005 01:10:28 -0000	1.11
+++ timeout.m	25 Apr 2005 07:21:54 -0000
@@ -14,7 +14,7 @@
 % creates a temporary file, it adds its name to the array; when it deletes
 % the temporary file, it deletes its name from the array. When we get an
 % unexpected signal, we clean up by deleting all the temporary files named
-% in the array. The 
+% in the array.
 %
 % We establish the exit action to clean up the files as soon as they are
 % created, but we don't want the parent process after the fork to delete them
@@ -62,8 +62,7 @@
 	% (The mutex file exists iff some process holds the lock.)
 	% If the bool is `yes', meaning debugging is enabled, do nothing.
 	%
-:- pred get_lock(bool::in, string::in,
-	io::di, io::uo) is det.
+:- pred get_lock(bool::in, string::in, io::di, io::uo) is det.
 
 	% Release the lock on the named mutex file if the bool is `no'.
 	% (The mutex file exists iff some process holds the lock.)
@@ -384,7 +383,6 @@
 	*/
 	MP_delete_cleanup_files();
 	exit(EXIT_SUCCESS);
-
 }
 
 void
@@ -566,7 +564,7 @@
 	/*
 	** Mercury exceptions do not cause signals. The default exception
 	** handler prints and error message and exits. To ensure that
-	** we delete up the files we need to clean up, we get the exit
+	** we delete the files we need to clean up, we get the exit
 	** library function to invoke MP_delete_cleanup_files through
 	** MP_handle_fatal_exception.
 	*/
cvs diff: Diffing notes
Index: notes/deep_profiling.html
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/deep_profiler/notes/deep_profiling.html,v
retrieving revision 1.2
diff -u -b -r1.2 deep_profiling.html
--- notes/deep_profiling.html	5 Jun 2001 04:49:12 -0000	1.2
+++ notes/deep_profiling.html	25 Apr 2005 07:52:19 -0000
@@ -193,10 +193,10 @@
 
 <h2>The Mercury deep profiling tool mdprof</h2>
 
-The Mercury deep profiler consists of four programs.
+The Mercury deep profiler consists of three programs.
 One is the web browser of the user's choice:
 this implements the user interface.
-The other three are mdprof, mdprof_cgi and mdprof_server.
+The other two are mdprof and mdprof_cgi.
 
 <dl>
 <dt> mdprof
@@ -204,7 +204,7 @@
 This a simple shell script.
 It is invoked by the web server in response to queries of the right form.
 It does nothing more than set up the PATH environment variable
-to contain the directory in which mdprof_cgi and mdprof_server were installed,
+to contain the directory in which mdprof_cgi was installed,
 and then invoke mdprof_cgi.
 <dt> mdprof_cgi
 <dd>
@@ -215,19 +215,19 @@
 an URL component containing the name of a profiling data file
 and a query specifying which part of that data file is to be displayed.
 Mdprof_cgi checks whether a server process already exists
-for the given profiling data file, and if not, it creates that process.
-It then sends it the query, passes the results back to the web server,
-and exits.
-<dt> mdprof_server
-<dd>
-This is a Mercury program.
-It reads in the profiling data file
-whose name is passed to it on the command line by mdprof_cgi,
+for the given profiling data file.
+If the answer is yes, it passes the query to the server,
+gets back the reply, gives it to the web server, and exits.
+If the answer is no, it reads in the named profiling data file,
 processes it to materialize information that is required by queries
 but is stored in the profiling data file only implicitly,
-and then goes into a loop awaiting queries.
-When it gets a query from mdprof_cgi, it answers the query
-and goes back to sleep.
+and answers the query directly.
+It then forks itself.
+The parent exits to let the web server finish rendering the generated page.
+The child process becomes a server process,
+which goes into a loop awaiting queries.
+When it gets a query from mdprof_cgi,
+it answers the query and goes back to sleep.
 It exits when it has not received a query for a set timeout period,
 which by default is thirty minutes,
 or when it receives a "query" telling it to shut down.
@@ -238,51 +238,72 @@
 <dd>
 </dl>
 
-The reason for the split between mdprof/mdprof_cgi and mdprof_server
-is simply that the web server requires the program it invokes to exit
-before it displays the page the program generates,
-and we don't want have to read and process the deep profiling data file
+The reason why we create the server process via a fork
+instead of simply making the initial mdprof_cgi process the server process
+is that the web server requires the program it invokes to exit
+before it displays the page the program generates.
+Doing without a server doesn't work
+because we don't want have to read and process the deep profiling data file
 for every page to be displayed,
 since that takes a significant fraction of a minute.
 The reason for the split between mdprof and mdprof_cgi
-is to make it easy to specify and to modify
-the name of the directory containing the server program.
+is to make it possible to specify some parameters of the deep profiler
+without needing to recompile a Mercury program or even needing to know Mercury.
 
 <p>
 
-Mdprof_cgi and mdprof_server communicate via a pair of named pipes, whose names
-have the form /var/tmp/mdprof_server_{from,to}_<i>mangled_data_file_name</i>.
+The elements of the interface between the client and server roles of mdprof_cgi
+are documented in interface.m.
+The client and server communicate via a pair of named pipes
+whose names include a mangled form of the data file name.
 (The mangling is required to replace any slashes in the name of the data file.)
 The existence of these files serves as an approximation of a lock;
 the idea is that they exist if and only if a server process
 for that data file is alive and serving queries via those pipes.
 Mdprof_cgi creates a server process for the data file
 if and only if these named pipes do not exist.
-They are created and destroyed only by mdprof_server,
-and they are always created and destroyed together.
-Mdprof_server creates them as soon as it starts
-and deletes them just before it exits.
-There is no race condition when the pipes are deleted:
-while a server process may exist for a very short while
-after the pipes are deleted,
-it will not do anything after that deletion except shut down.
-There <i>is</i> a race condition when the pipes are created.
+They are created only by mdprof_cgi transforms itself into a server,
+and destroyed only when this server exits.
+The two files are always created and destroyed together.
+
+<p>
+
+There are potential race conditions
+both when the pipes are created and when they are destroyed.
 It is possible for the web server to receive two requests
 for a given data file in quick succession,
 and it is possible that when the second invocation of mdprof_cgi
 checks whether the pipes exist,
 the first invocation of mdprof_cgi
-either has not yet created the server process
-or that the server process has not yet created the pipes.
-However, the window of vulnerability is small,
-the likelyhood that two different users will start mdprof browsing sessions
-during that window is very small,
-and the likelyhood that one user will start two different sessions
-during that window is even smaller.
-The mechanisms required for locking would in any case be
-operating system dependent.
-Since the programming cost is significant and the benefits are not,
-we simply live with the window of vulnerability.
+has not yet forked itself off as a server process.
+We avoid this by putting all code
+that creates, destroys, or test the existence of the named pipes
+inside a critical region protected by a lock on a mutex file.
+Whichever invocation of mdprof_cgi gets the lock first will become the server;
+any others will not be able to perform the test for the existence of a server
+until after there is a server.
+
+<p>
+
+The other race condition involves a client arriving
+between the time that the server gets the timeout signal
+and the time that the server actually deletes the named pipes and exits.
+To fix this, we make clients create a file indicating that they want a server
+before they get the lock on the mutex file.
+If the shutting-down server gets the mutex first,
+it will abort the shutdown if it finds any want files around.
+If it does not find any want files, it shuts down,
+but because it holds the mutex lock throughout the process of shutdown,
+no client can observe its decision process.
+
+<p>
+
+In the absence of the want files,
+a server that got a timeout signal would have no decision to make.
+It would therefore be possible for a client to arrive
+and find that the named pipes exist,
+without knowing that the server process is already committed to shutting down,
+which can leave the client sending its query to a now nonexistent server.
 
 <hr>
 <!---------------------------------------------------------------------------->
@@ -290,6 +311,20 @@
 <h2>The modules of the deep profiler</h2>
 
 <dl>
+<dt> mdprof_cgi.m
+<dd>
+This file contains the program that is executed by the web server
+to handle each web page request.
+<dt> mdprof_dump.m
+<dd>
+This is the main module of a program
+for dumping out the contents of Deep.data files,
+for use in debugging.
+<dt> mdprof_test.m
+<dd>
+This is the main module of a test program for checking that
+all the web pages can be created without runtime aborts.
+Its output can be gigabytes in size.
 <dt> array_util.m
 <dd>
 This module contains utility predicates for handling arrays.
@@ -319,56 +354,54 @@
 This module provides an ADT for storing dense sets of small integers.
 The sets are represented as bit vectors, which are implemented as arrays
 of integers. This is used by cliques.m.
+<dt> dump.m
+<dd>
+This module provides a mechanism for dumping out some of the deep profiler's
+data structures for debugging.
+<dt> exclude.m
+<dd>
+This module implements contour exclusion,
+which is a mechanism for propagating measurements
+from regions in the call graph below a given line (the contour) to that line.
+<dt> html_format.m
+<dd>
+This module contains code that sets the format of the HTML tables
+we generate for individual queries.
 <dt> interface.m
 <dd>
-This module defines the type of the commands
-that mdprof_cgi passes to mdprof_server,
+This module defines the type of the commands sent from clients to servers,
 as well as utility predicates for manipulating commands and responses.
 <dt> io_combinator.m
 <dd>
 This module a set of I/O combinators for use by read_profile.m.
-<dt> mdprof_cgi.m
-<dd>
-This file contains the program that is executed by the web server
-to handle each web page requests.
-<dt> mdprof_server.m
-<dd>
-This file defines the top level predicates of mdprof_server.
-It is mostly concerned with option handling.
 <dt> measurements.m
 <dd>
 This module defines the data structures
 that store deep profiling measurements
 and the operations on them.
-<dt> merge.m
-<dd>
-This module contains code for recursively merging
-sets of ProcDynamic and CallSiteDynamic nodes.
-mdprof_uses this code to make sure that each clique contains
-at most ProcDynamic structure for any given procedure.
 <dt> profile.m
 <dd>
-This file defines the main data structures of mdprof_server,
+This file defines the main data structures of the server,
 and predicates for accessing them.
+<dt> query.m
+<dd>
+This module contains the top level predicates for servicing individual queries.
 <dt> read_profile.m
 <dd>
-This module contains code for reading in the deep profiling data files
-created by deep profiled executables.
-<dt> server.m
-<dd>
-This module contains the main server loop of mdprof_server;
-each iteration of the server loop serves up one web page.
-The module also contains test code for checking that all the web pages
-can be created without runtime aborts.
+This module contains code for reading in a deep profiling data file.
 <dt> startup.m
 <dd>
-This module contains the code for turning the raw list of nodes read in by
-read_profile.m into the data structure that mdprof_server needs to service
-requests for web pages.
+This module contains the code
+for turning the raw list of nodes read in by read_profile.m
+into the data structure that the server needs
+to service requests for web pages.
 <dt> timeout.m
 <dd>
-This module implements the timeouts that mdprof_server uses
+This module implements the timeouts that mdprof_sgi uses
 to shut down after it hasn't received any queries for a while.
+<dt> top_procs.m
+<dd>
+This module contains code to find the top procedures by several criteria.
 <dt> util.m
 <dd>
 This module defines utility predicates for both mdprof_cgi and mdprof_server.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------