"scm/TODO"
	$Id: TODO,v 1.6 2007/09/28 05:37:01 fang Exp $

Populate this directory with Scheme modules for working with HACKT.

Top priority: hackt's chpsim trace interface for analysis (under way)

accessor functions to event-node-ptr SMOB
	type info [partially done, in the form of predicates, can be refined]
	predecessors (will take some effort to construct)
	may-read/write dependencies

other stream interfaces:
	stream of *read* (accessed) state/variables? may be difficult
	[priority: low]

slack-time annotation?
	requires reconstructing precise causality graph of all events?
		could be major memory hog...
	starting point might be list of necessary predecessor
	execution path reconstruction from branch-tracing
	also assumes constant delay per-event for backwards inference

scm structures for variable sets
	plain list of references (type-index pairs)
	somewhat exists with reference-value lists per trace event

stream merge algorithms (like set_intersection, set_union, set_difference)
	precondition: streams already sorted/ordered

histogram of event frequency, by counting immediate successors of selections
	use either a vector or sparse representation

canonical-type interfacing to SCM

FIFO-identification for automatic slack-matching
	would be a static analysis for a FIFO event pattern, 
		following producer/consumer chains, and send/receive 
		tight loops.
	idea: look at the may-block set of send/receive events
		and follow unique reference chains of channels.  
	construct a map (rb-tree) using head of fifo as canonical key.
	with two ends of FIFO, can measure average FIFO occupancy
		over time, based on entry and exits!

testing:
	have scripts exit-upon-first-error, to simplify debugging

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
source-referencing: be able to refer events back to source in context?
	[priority: HIGH -- dissertation]
	[status: DONE on -00-01-04-main-00-81-75-CHP-03 branch]

===============================================================================
ANALYSIS ROUTINES: mostly for thesis work

usability:
	outputs of analysis should reference names, not numbers, 
		so do the reverse-lookup

channel action pairs: send or receive critical? how often?
	sift by event or by channel?  
	there's a difference when channels are non-meta indexed.
	can start by analyzing ALL channels this way.

value-based time profiling:
	define event intervals based on value/state predicates, 
		or transitions.  
	similar to stream crop, with general set of predicates.
	construct chronologically sorted interval sets
		define interval set operations
	aside: translate event intervals to time intervals, re-usable.  

Dynamic dataflow:
	trace the impact of a particular variable, like poison trace
	requires: dynamic read-tracing

temporal logic: `when?' queries
	in general, formulate from interval sets

phase detection: examples where behavior characteristic is temporally local,
	detecting transitions, etc...

basic:
	Q: what is value of variable X at time T?
	A: find stamp of last value changed, which requires a trace 
		reverse seek.  
	Or can just take entire history of variable and step back, 
		which is faster for re-usable queries, but not one-time query.  

replay:
	can checkpoints be 'inferred' in reasonable time from trace alone?

===============================================================================
NAMING CONVENTION:

Currently, all primitive functions are prefixed with 'hac:'
and scheme functions built on top of them don't have any prefix.
We CAN re-export the 'hac:' primitive functions without their prefix
in the scheme modules (define-public hac:func func).

===============================================================================
BUGS:
	branch count is off by 1 for branches that are loop-heads and
		also happen to be an exit branch of do-while loop
		because first entry to do-while gets counted as a 
		loop-back branch.  Severity: minor.

===============================================================================
DOCUMENTATION

is tentatively being done by registering docstrings to guile's interpreter,
to be generated by some print-all function, invoked from hacguile, 
or hacchpsimguile.

Dilemma: where do we generation documentation from: 
	hacguile vs. hacchpsimguile?
Should/can documentation be generated separately and modularly?
hacchpsimguile is a superset of hacguile, but future programs will also
spawn from hacchpsimguile.  Best design approach might be to do away
with hacchpsimguile as an executable and only load as a module.
Then the future documentation-generator can just load every available
module for the sake of generating complete documentation.  

Hmm...

guile has 'procedure-documentation' function that looks for embedded
string for documentation inside function bodies.  
TODO: collect all hackt-scheme functions in modules (module-reflection)
and export documentation to texinfo.  

NEW IDEA:
Now that we've learned texinfo, we could just extract the documentation 
directly from source, which doesn't require running guile to extract
the documentation.  However, this doesn't help provide online
in-rogram documentation.
There might be a good way to provide procedure-documentation strings
with texinfo excerpts...

