Merge lp:~epics-documenters/epics-appdev/ioc-shutdown into lp:~epics-documenters/epics-appdev/3.16

[Ralph Lange]

Documentation for iocInit changes.

See https://code.launchpad.net/~epics-core/epics-base/ioc-shutdown

[Andrew Johnson (anj)]

Docs need revising to cover the ioc-shutdown2 changes.

review: Needs Fixing

=== modified file 'tex/generalPurposeTasks.tex'
--- tex/generalPurposeTasks.tex	2010-11-15 18:16:16 +0000
+++ tex/generalPurposeTasks.tex	2013-10-11 00:45:39 +0000
@@ -127,6 +127,7 @@
 The following calls are provided:
 
 \index{callbackInit}
+\index{callbackShutdown}
 \index{callbackSetCallback}
 \index{callbackSetPriority}
 \index{callbackSetUser}
@@ -141,6 +142,7 @@
 Notes:
 \begin{verbatim}
 void callbackInit(void);
+void callbackShutdown(void);
 
 void callbackSetCallback(void *pcallbackFunction,
     CALLBACK *pcallback);
@@ -160,7 +162,8 @@
 \end{verbatim}
 
 \begin{itemize}
-\item \verb|callbackInit| is performed automatically at IOC initialization, thus user code never calls this function.
+\item \verb|callbackInit| and \verb|callbackShutdown| are performed automatically at IOC initialization or shutdown,
+thus user code never calls these functions.
 
 \item \verb|callbackSetCallback|, \verb|callbackSetPriority|, \verb|callbackSetUser|, and \verb|callbackGetUser| are 
 actually macros.

=== modified file 'tex/libCom.tex'
--- tex/libCom.tex	2012-01-17 18:04:20 +0000
+++ tex/libCom.tex	2013-10-11 00:45:39 +0000
@@ -1567,6 +1567,26 @@
 call to the runTestFunc() routine.
 The last test program or the harness program itself must finish by calling epicsExit() which triggers the test summary mechanism to generate its result outputs (from an epicsAtExit callback routine).
 
+Some tests require the context of an IOC to be run. This conflicts with the idea of running multiple tests within a test harness, as iocInit() is only allowed to be called once, and some parts of the full IOC (e.g., the rsrv CA server) can not be shut down cleanly.
+The function iocBuildNoCA() allows to start an IOC without its Channel Access parts, so that it can be shutdown quite cleany using iocShutdown(). This feature is only intended to be used from test programs. Do not use it on productional IOCs. After building the IOC using iocBuildNoCA() or iocBuild(), it has to be started by calling iocRun(). The suggested call sequence in a test program that needs to run the IOC without Channel Access is:
+
+\begin{verbatim}
+#include "iocInit.h"
+
+MAIN(iocTest)
+{
+    iocBuildNoCA() || iocRun();
+
+[... test code ...]
+
+    iocShutdown();
+    dbFreeBase(pdbbase);
+    registryFree();
+    pdbbase = NULL;
+    return testDone();
+}
+\end{verbatim}
+
 To make it easier to create a single test program that can be built for both the embedded and workstation operating system harnesses, the header file \verb|testMain.h| provides a convenience macro MAIN() that adjusts the name of the test program according to the platform it is running on: main() on workstations and a regular function name on embedded systems.
 
 \index{testMain.h}