-*- Mode:Text; Fonts:(COURIER MEDFNB) -*-

This file will attempt to explain submetering, its
relationship with the released metering, and how 
to use it.

Submetering microcode support is in the "Release 5"
microcode database.  It only runs on the Explorer 2
or the MX.  Therefore, you need to have a microcode
whose version number is greater or equal to 309 
(for Explorer 2) or 66 (for MicroExplorer).

Basically, submetering can do everything that metering
will do (except for one thing) and do it faster!!
Also there is no need for the METR partition or for
turning GC off.  The real big gain then in using 
submetering is that you can "submeter" a much 
larger dynamic set.  Maybe I should have called
it "supermeter".  

The one exception is the CALL TREE DATA.  
That is, metering will supply the information
that a particular function is using up CPU resources and
you can then find out who called that function.
This is particularly useful when lower-level system
functions are eating up resources.

To use submetering follow these guidelines:

0.  Ensure that you are on an Explorer 2 or a MicroExplorer
    running microcodes 309+ or 66+ respectively.

1.  Boot the system and load the file "SYS:PUBLIC;SUBMETER".

2.  Initialize the submeter data structures by executing
	(SI:SUBMETER-INITIALIZE).
    This function has two optional keywords:
      :FUNCTIONS specifies the approximate number of 
	 functions that you think will run.  The default
	 is 2048. (a power of 2.)  I used 8192. for the
	 interactives (25 minutes of run time).  See the
	 documentation string for more information.
      :ITEMS specifies what to submeter.  If you do not
	 specify anything here then everything (all processes)
	 will be submetered.  This is the most common
         form of execution, with a without-interrupts wrapped
	 around the form to submeter.  But you can specify 
	 here to submeter only a particular process or a list
	 of processes.

3.  Execute SUBMETER-ENABLE. This starts the submetering.

4.  Execute SUBMETER-DISABLE.  This stops the submetering.

	You can go back and re-enable.  Data is just accumulated.
	A common use is
	(SI:SUBMETER-INITIALIZE)
	(WITHOUT-INTERRUPTS
		(SI:SUBMETER-ENABLE)
			..
			BODY
			..
		(SI:SUBMETER-DISABLE))
	(DRIBBLE-START "fn")
	(SI:SUBMETER-REPORT)
	(DRIBBLE)

5.  Execute SUBMETER-REPORT.  Here the doc string should suffice.
	Notice in the above example the usage of dribble.
	There is no nice dump the output to a specified file.


