add the ability to bind signal handlers

and a useful example one ;)

this also involved fixing the failure cases in input.e to handle EINTR correctly. it required a lot of tracing, but now the expected state of the stack is much better commented for next time.

many thanks to @cks@mastodon.social who found code in the Go compiler which had the details of what's required in regard to the restorer, which made the whole thing work, and to @snowfox@tech.lgbt who did some experimental testing around the exact requirements. both those contributions are reflected in the documentation added with this CL. additional thanks to everyone who chimed in on the fedi thread, your comments kept us going!

Force-Push: yes
Change-Id: I97fd89426bf807df5565e011d3665f7e904fa138

1 files changed, 15 insertions, 0 deletions

diff --git a/execution.e b/execution.e
index 0aa5491..7a10e70 100644
--- a/execution.e
+++ b/execution.e
@@ -147,6 +147,21 @@
 
 ~   The macros next, beforenext, pushcontrol, and popcontrol are implemented
 ~ in execution-support.e. It's a good idea to go read about them now.
+~
+~ TODO the following high-level summary should go... somewhere?
+~   When a docol word is invoked, it immediately does pushcontrol (see
+~ execution-support.e) to push rsi onto the control stack, whose top is
+~ indicated by rbp. When an assembly word is invoked, it leaves rsi and rbp
+~ alone; assembly words don't normally call other words, so there's no need
+~ for them to appear on the control stack at all.
+~
+~   When an assembly word returns, it looks for an execution token pointed
+~ to by rsi, increments rsi, and invokes that word as if calling it. This
+~ is the threaded calling approach to Forth execution. When a docol word
+~ returns, it calls exit, which needs to remove itself from the control
+~ stack, so exit pops the top of the control stack into rsi to get back into
+~ its caller's context, then does the same steps an assembly word would do.
+
 
 ~ Constants
 ~ ~~~~~~~~~