SixtyPical/tests/SixtyPical Fallthru.md

SixtyPical Fallthru
===================

This is a test suite, written in [Falderal][] format, for SixtyPical's
ability to detect which routines make tail calls to other routines,
and thus can be re-arranged to simply "fall through" to them.

The theory is as follows.

SixtyPical supports a `goto`, but it can only appear in tail position.
If a routine r1 ends with a unique `goto` to a fixed routine r2 it is said
to *potentially fall through* to r2.

A *unique* `goto` means that there are not multiple different `goto`s in
tail position (which can happen if, for example, an `if` is the last thing
in a routine, and each branch of that `if` ends with a different `goto`.)

A *fixed* routine means, a routine which is known at compile time, not a
`goto` through a vector.

Consider the set R of all routines in the program.

Every routine r1 ∈ R either potentially falls through to a single routine
r2 ∈ R (r2 ≠ r1) or it does not potentially fall through to any routine.
We can say out(r1) = {r2} or out(r1) = ∅.

Every routine r ∈ R in this set also has a set of zero or more
routines from which it is potentially falled through to by.  Call this
in(r).  It is the case that out(r1) = {r2} → r1 ∈ in(r2).

We can trace out the connections by following the in- or our- sets of
a given routine.  Because each routine potentially falls through to only
a single routine, the structures we find will be tree-like, not DAG-like.

But they do permit cycles.

So, we first break those cycles.  (Is there a "best" way to do this?
Perhaps.  But for now, we just break them arbitrarily; pick a r1 that
has a cycle and remove it from in(r2) for all r2. This also means
that, now, out(r1) = ∅.  Then check if there are still cycles, and keep
picking one and breaking it until there are no cycles remaining.)

We will be left with out() sets which are disjoint trees, i.e.
if r1 ∈ in(r2), then r1 ∉ in(r3) for all r3 ≠ r2.  Also, 
out(r1) = ∅ → for all r2, r1 ∉ in(r2).

We then follow an algorithm something like this.  Treat R as a mutable
set and start with an empty list L.  Then,

- Pick a routine r from R where out(r) = ∅.
- Find the longest chain of routines r1,r2,...rn in R where out(r1) = {r2},
  out(r2} = {r3}, ... out(rn-1) = {rn}, and rn = r.
- Remove (r1,r2,...,rn) from R and append them to L in that order.
  Mark (r1,r2,...rn-1) as "will have their final `goto` removed."
- Repeat until R is empty.

When times comes to generate code, generate it in the order given by L.

[Falderal]:     http://catseye.tc/node/Falderal

    -> Functionality "Dump fallthru info for SixtyPical program" is implemented by
    -> shell command "bin/sixtypical --optimize-fallthru --dump-fallthru-info --analyze-only --traceback %(test-body-file)"

    -> Tests for functionality "Dump fallthru info for SixtyPical program"

A single routine, obviously, falls through to nothing and has nothing fall
through to it.

    | define main routine
    | {
    | }
    = {}
    = *** serialization:
    = [
    =     [
    =         "main"
    =     ]
    = ]

If main does a `goto foo`, then it can fall through to `foo`.

    | define foo routine trashes a, z, n
    | {
    |     ld a, 0
    | }
    | 
    | define main routine trashes a, z, n
    | {
    |     goto foo
    | }
    = {
    =     "foo": [
    =         "main"
    =     ]
    = }
    = *** serialization:
    = [
    =     [
    =         "main", 
    =         "foo"
    =     ]
    = ]

More than one routine can fall through to a routine.  We pick one
of them to fall through, when selecting the order of routines.

    | define foo routine trashes a, z, n
    | {
    |     ld a, 0
    | }
    | 
    | define bar routine trashes a, z, n
    | {
    |     ld a, 0
    |     goto foo
    | }
    | 
    | define main routine trashes a, z, n
    | {
    |     goto foo
    | }
    = {
    =     "foo": [
    =         "bar", 
    =         "main"
    =     ]
    = }
    = *** serialization:
    = [
    =     [
    =         "main", 
    =         "foo"
    =     ], 
    =     [
    =         "bar"
    =     ]
    = ]

There is nothing stopping two routines from tail-calling each
other, but we will only be able to make one of them, at most,
fall through to the other.

    | define foo routine trashes a, z, n
    | {
    |     ld a, 0
    |     goto bar
    | }
    | 
    | define bar routine trashes a, z, n
    | {
    |     ld a, 0
    |     goto foo
    | }
    | 
    | define main routine trashes a, z, n
    | {
    | }
    = {
    =     "bar": [
    =         "foo"
    =     ], 
    =     "foo": [
    =         "bar"
    =     ]
    = }
    = *** cycles found:
    = [
    =     "bar", 
    =     "foo"
    = ]
    = *** after breaking cycle:
    = {
    =     "bar": [
    =         "foo"
    =     ]
    = }
    = *** serialization:
    = [
    =     [
    =         "main"
    =     ], 
    =     [
    =         "bar", 
    =         "foo"
    =     ]
    = ]

If a routine does two tail calls (which is possible because they
can be in different branches of an `if`) it cannot fall through to another
routine.

    | define foo routine trashes a, z, n
    | {
    |     ld a, 0
    | }
    | 
    | define bar routine trashes a, z, n
    | {
    |     ld a, 0
    | }
    | 
    | define main routine inputs z trashes a, z, n
    | {
    |     if z {
    |         goto foo
    |     } else {
    |         goto bar
    |     }
    | }
    = {}
    = *** serialization:
    = [
    =     [
    =         "main"
    =     ], 
    =     [
    =         "bar"
    =     ], 
    =     [
    =         "foo"
    =     ]
    = ]

Similarly, a tail call to a vector can't be turned into a fallthru,
because we don't necessarily know what actual routine the vector contains.

    | vector routine trashes a, z, n
    |   vec
    | 
    | define foo routine trashes a, z, n
    | {
    |     ld a, 0
    | }
    | 
    | define bar routine trashes a, z, n
    | {
    |     ld a, 0
    | }
    | 
    | define main routine outputs vec trashes a, z, n
    | {
    |     copy bar, vec
    |     goto vec
    | }
    = {}
    = *** serialization:
    = [
    =     [
    =         "main"
    =     ], 
    =     [
    =         "bar"
    =     ], 
    =     [
    =         "foo"
    =     ]
    = ]