AssemblerSemantics

The assembler functionality common to (all of?) the backends could be better documented.

For example, PnkFelix just spent the morning trying to figure out why his assembly structure was being processed multiple times. But that wasn't actually the problem; the problem is that he was maintaining state in the backend-specific user-data structure, assuming that it would be created for each instance of the assembler structure. When that turned out to be false, he found the places in the backend code that he needed to update that would create fresh user-data structures for every assembler structure; the backend seems like a sensible place to store that sort of per-backend policy information, if we're going to allow the policy to vary at all.

But then it turns out that the backend isn't the only place where the user-data structures are created; in particular, compile-file in the driver-twobit.sch source creates one user-data structure per file. And therefore the policy isn't isolated to the backends alone; we're pretty much stuck with maintaining a "global" user-data structure across the compilation.

PnkFelix thinks he can solve his immediate problem without mucking further with the user-data stuff. (All we was trying to do was track labels declared in the MacScheme source, but it turns out that there should be the right machinery to do this built into the main assembly structure; PnkFelix just needs to start calling make-asm-label to update that structure).

• Actually, he later realized that he was relying on having per-assembler-structure state available. It could be that the usage pattern employed by compile-file was compatible with the usage he was thinking of, but it really isn't the right way to go. So he's almost certainly going to add the structure described in the bullets below.

But it would be good to:

• Document the assembler code. At the very least, we could add contracts to the functions!
• Add a per-assembler-structure, backend-defined user data field. Then update the pieces of code (like compile-file) to properly construct them for each assembly structure.
  • Actually, since the structure is generated on a per-assembler-structure basis, its sufficient to just update the constructor for the assembly-structure. That's assuming that we're happy always starting with the initial state for the user data and using imperative update to change it as we proceed.