C/Tcl Interface: Interrupt Handling
This page describes the itf module's interrupt handling services. There are four signals that Janus 3 can handle:
- SIGINT which is usually sent by controll-C (or kill -INT)
- SIGTERM which is usually sent during system shutdown (or kill -TERM)
- SIGUSR1 which is usually sent by communicating processes (or kill -USR1)
- SIGUSR2 which is usually sent by communicating processes (or kill -USR2)
SIGINT
When JANUS receives a SIGINT and it's standard input is a tty (i.e. JANUS is running interactively in a terminal),
then it will stop the execution of the running program at the next safe state. It will notify the user immediately after
receiving the signal, but it won't accept any input before the currently running atomic Tcl command is finisched. I.e. that
if the currently running command is a C function, then Tcl regards it as atomic, and will wait until the C function returns.
This can result in long waiting times in some cases. This behaviour is necessary because it is very unsafe to tell the Tcl
interpreter to start a new command while it is already executing another. So far there is no safe way to abort a longrunner
C function.
While JANUS is handling an interrupt, it will not accept further interrupts. Keep in mind that any command you start in
interrupt mode can not be aborted with controll-C. When you enter the interrupt mode, you will get the prompt %%
instead of % (and while entering unfinished commands, the prompt will be >> instead of >.
You can exit the interrupt mode in at least six different ways:
- If you enter CONT (all caps!) then the program execution will continue from where it stopped. The Tcl error status will
remain unchanged (i.e. it will stay as it was left by the last command that was executed). The message when entering interrupt mode
looks like
CONT to continue (returning n), BREAK to abort
where n is the result of the
last command (0=TCL_OK, 1=TCL_ERROR).
- If you enter BREAK (all caps!) then the program execution will stop. You will end up in the top-level Tcl shell.
- If you enter CONTOK (all caps!) then the program execution will continue even if the last command produced an error. This
is usefull, if you have typed controll-C while something was being written to standrd output. This makes Tcl think that
an error has occurred. CONTOK will continue the program in any case, even if a 'real' error has occurred.
- If you enter CONTERROR (all caps!) then the program execution will continue as if the last command had produced an error
even if it didn't. This does not necessarily mean that the entire program gets stopped.
- If you enter exit (the Tcl command) then you will leave JANUS completely.
- If you type controll-D it will behave like entering BREAK. So the fastest way to stop a running command and returning to
the regular shell is typing controll-C controll-D.
SIGTERM
Usually when a system is shut down, the shutdown process will send a TERM signal to every process some seconds before it
sends them a KILL signal. You can use this time to do some emergency-save of the current status, e.g. saving the training
accumulators or something that will allow you to continue the job later. You can define yourself what you want to happen when a
TERM signal is received, by defining a Tcl procedure sigTermScript (no arguments). This procedure will then be executed.
SIGUSR1 SIGUSR2
You can define two Tcl procedures sigUsr1Script and sigUsr2Script which will be executed, whenever the program
receives a USR1 or a USR2 signal. These signals can be used to communicate to a JANUS process that is running in
the background. You could, for example, define
proc sigUsr1Script { } { source sigUsr1File }
Then you can edit the file "sigUsr1File", send JANUS a USR1 signal, and make it execute what is in the File. Or
proc sigUsr1Script { } {
set fp [open outputFile w] ;
puts $fp [doSomething] ;
close $fp
}
Then you can trigger the output of the doSomething command into the file outputFile. This way you can get
complex status reports from a background-running JANUS process whenever you like.