guile-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

plan for merging guile-vm docs into guile manual


From: Andy Wingo
Subject: plan for merging guile-vm docs into guile manual
Date: Thu, 06 Nov 2008 14:07:04 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.60 (gnu/linux)

Greetings Guilers,

I've been looking at the VM, and as far as I can tell, what's needed
before it can be merged into master is just documentation. All the rest
of it can be improved while it's in master, but it offers no significant
regression.

The biggest regression that I know of is that the traps interface
won't work with compiled code. I think this is fixable though --
although probably we'll have to hack on traps. I have some thoughts
this, for a later time.

Anyway. I think the place for VM docs is in the Guile manual, and so I
just read through the whole manual, and what exists of the VM manual,
trying to figure out a plan.

The general plan that I've come up with is that we should interleave
notes about compilation through the manual in all places that we talk
about evaluation or memoization, and then at the end of the manual, we
should add a separate toplevel section: "History and Implemention
Details".

We would fold in the "Data representation" into this section, and use it
to talk about where Guile has come from (something I've always thought
is lacking, in our public narrative), how it is implemented today, and
where it's going (generally speaking).

So we can talk about the memoizer/evaluator and its strengths, its
principles of a highly dynamic development environment, its origins in
"low-latency programming", in which we reduce to the minimum the delay
between writing code and having it active.

At that point we can talk about the data representation used in Guile,
as coming from SCM and being one of the fastest hand-coded interpreters
out there.

But then we can talk about the compiler, and how it is a new feature,
retrofitted on top of a large existing body of code, both C and Scheme,
and on top of a large body of deployed users. Hence we can justify many
of the design decisions: use of the VM and all.

At that point we talk about the VM and its model: its registers, its
memory model, its execution model, the representation of programs in
memory, the representation of compiled code on disk, heap, stack, and
toplevel variables, etc.

Then we can describe the interface of the compiler: `compile' and
`compile-file', `guile-tools compile', and the disassembler. Perhaps
this section could actually go in the main reference, along with
documentation for `load', `eval', et al.

Then we can talk about the implementation of the compiler, its
multilingual translation system, GHIL, GLIL, and all the rest. (It would
be good to add GHIL and GLIL language definitions, so you can type them
in directly at the REPL.) Also what optimizations the compiler
implements, notes on performance, and some suggestions for future
directions (JIT, etc). We can also devote a section to the VM
instruction set around here, including a section on how to add new
instructions, issues of compiled code compatibility, and when it is
appropriate to add a new instruction.

So that's the plan. Thoughts on the new section, or otherwise?

Andy
-- 
http://wingolog.org/




reply via email to

[Prev in Thread] Current Thread [Next in Thread]