_____
 ---'   __\_______
            ______)         Interruptible poke
            __)
           __)
 ---._______)

                                                      Jose E. Marchesi
                                                      March 02, 2020


Poke has loops.  It also does IO (yeah, right :D).  On one hand, this
means that Poke programs that never finish are definitely possible
(here is one: `while (1) {}') and, on the other, a Poke program acting
on an enormous amount of data may take a long time to finish,
depending on what it does.  Maybe hours, maybe even days?


So there are reasons for wanting to interrupt a running Poke program.
Since this weekend, this is as easy as pressing `Ctrl-C' in the
command line while a Poke program is running, or sending `SIGQUIT' to
it:

	(poke) while (1) { }
	Ctrl-C
	(poke)

How does this work?  First, Luca got some simple infrastructure for
this in Jitter, in the form of an array called
JITTER_PENDING_NOTIFICATIONS that contains a counter for every
possible signal.  Every time poke runs some PVM code, it temporarily
installs a handler for SIGQUIT that notes the signal in the pending
notifications array.

How is the running program made aware of the presence of the signal?
The Poke compiler generates `sync' instructions in strategic places,
such as before the backward jump in loops:

	(poke) fun foo = void: { while (1) {} }
	(poke) .vm dis f foo
	        note   <span class="string">&quot;foo&quot;</span>
	$L1:
	        prolog
	        pushf
	$L3:
	        push   <span class="integer">0x1</span>
	        bzi    $L10
	        drop
	        pushf
	        popf   1
	        sync
	        ba     $L3
	$L10:
	        drop
	        popf   1
	        push   null
	        return
	        exitvm

When the `sync' instruction is executed, it checks
'JITTER_PENDING_NOTIFICATIONS', and raises a `PVM_E_SIGNAL' exception.
The default signal handler handles this exception just exiting the
program silently.

Happy poking!