PSI sics-cvs-psi_pre-ansto

doc/programmer/interrupt.tex

@@ -0,0 +1,53 @@
+\subsection{Interrupt Handling}
+	 SICS needs a way to interrupt server processsing. This is done
+	 with this module.
+	 Interrupts may come in through two ways: They may be created
+	 internally or they may be user requested. For the last ones
+	 the main loop will poll an additional special interrupt
+	 port.
+
+In order to do interrupting a set of interrupt codes are defined:
+\begin{verbatim}
+#define eContinue   0
+#define eAbortOperation  1
+#define eAbortScan       2
+#define eAbortBatch 3
+#define eHaltSystem 4
+#define eFreeSystem 5
+#define eEndServer  6
+\end{verbatim}
+Their meanings:
+\begin{description}
+\item[eContinue] Go on, interrupt nothing.
+\item[eAbortOperation] stop current hardware operation but no scans or
+batchfiles.
+\item[eAbortScan] stop current scan or operation but continue processing of
+batch files with next command.
+\item[eAbortBatch] Stop all processing, even batch files.
+\item[eHaltSystem, eFreeSystem] are currently unused.
+\item[eEndServer] is used internally by the SicsExitus command to run down
+the server. 
+\end{description}
+
+The interrupt module supports the following interface:
+\begin{description}
+\item[void ServerStopInterrupt(void)] stops interrupt processing.
+\item[void SetInterrupt(int iCode)]
+    Send an interrupt to all connections. Use with care! More often an
+interrupt need to be set on a special connection. This can be done with
+SCSetInterrupt defined in conman.h.
+\item[int Interrupt2Text(int iInterrupt, char *text, int iTextLen)] converts
+iInterrupt to a text. Maximum iTextLen characters will be copied to text.
+\item[int Text2Interrupt(char *text)] Converts text, when applicable to an
+interrupt code which is returned. If the text is invalid -1 is returned.
+\item[int ClientSetupInterrupt(char *host, int iPort)] Creates a client side
+interrupt UDP port. 
+\item[void ClientStopInterrupt(void)] removes an client side interrupt port
+created by ClientSetupInterrupt.
+\item[void SendInterrupt( int iCode)] sends an interrupt through the UDP
+port.
+\end{description}   
+
+Please note, that the interrupt implementation is distributed into two
+files: intserv.c for the server side stuff and intcli.c for the client side
+part. UDP interrupting is not fully tested.