sharedspice.c: improved comments

src/sharedspice.c

@@ -17,8 +17,10 @@
 #endif
 
 
-/* The Delphi Interface has high latency times during printing,
-   therefore undef the following line */
+/* If a calling function has high latency times during printing,
+   causing memory access errors, you may undef the following line.
+   Printing messages are assembled in a wordlist, and sent to the caller
+   via a new thread. Delays may occur. */
 #define low_latency
 
 /**********************************************************************/
@@ -304,6 +306,7 @@ static bool ps_exited = TRUE;
 #define EXPORT_FLAVOR
 #endif
 
+/*  starts a background thread, e.g. from command bg_run */
 static void * EXPORT_FLAVOR
 _thread_run(void *string)
 {
@@ -329,7 +332,7 @@ _thread_run(void *string)
 }
 
 
-/*Stops a running thread, hopefully */
+/*Stops a running background thread, hopefully */
 static int EXPORT_FLAVOR
 _thread_stop(void)
 {
@@ -379,7 +382,7 @@ sighandler_sharedspice(int num)
 
 #endif /*THREADS*/
 
-
+/* run a ngspice command */
 static int
 runc(char* command)
 {
@@ -487,7 +490,7 @@ runc(char* command)
 
 #ifdef THREADS
 
-/* Checks if spice is running in the background        */
+/* Checks if ngspice is running in the background        */
 IMPEXP
 bool
 ngSpice_running (void)
@@ -497,7 +500,7 @@ ngSpice_running (void)
 #endif
 
 
-/*  Initialise spice and setup native methods          */
+/*  Initialise ngspice and setup native methods          */
 IMPEXP
 int
 ngSpice_Init(SendChar* printfcn, SendStat* statusfcn, ControlledExit* ngspiceexit, 
@@ -681,7 +684,6 @@ IMPEXP
 int  ngSpice_Command(char* comexec)
 {
     if ( ! setjmp(errbufc) ) {
-//       HANDLE tid2;
     
         immediate = FALSE;       
         intermj = 1;
@@ -690,12 +692,9 @@ int  ngSpice_Command(char* comexec)
            fprintf(stderr, no_init);
            return 1;
        }
-//       tid2 = (HANDLE)_beginthreadex(NULL, 0, (PTHREAD_START_ROUTINE)runc, (void*)comexec,
-//                         0, NULL);
+
        runc(comexec);
-       /* main thread prepares immediate detaching of dll,
-       in case of controlled_exit from tid2 thread, caller is asked
-       to detach dll via fcn ngexit() */
+       /* main thread prepares immediate detaching of dll */
        immediate = TRUE;
        return 0;
     }
@@ -832,8 +831,8 @@ char** ngSpice_AllVecs(char* plotname)
 /* Redefine the vfprintf() functions for callback       */
 /*------------------------------------------------------*/
 
-/* handling of escape characters (extra \ added) is removed, may be added by 
-   un-commenting some lines */
+/* handling of escape characters (extra \ added) only, if 
+   'set addescape' is given in .spiceinit */
 
 int
 sh_vfprintf(FILE *f, const char *fmt, va_list args)
@@ -912,7 +911,7 @@ sh_vfprintf(FILE *f, const char *fmt, va_list args)
         }
     }
 
-    /* use sharedspice implementation of fputs (sh_fputs)
+    /* use sharedspice.c implementation of fputs (sh_fputs)
        to assess callback function derived from address printfcn received via
        Spice_Init() from caller of ngspice.dll */
 
@@ -926,9 +925,10 @@ sh_vfprintf(FILE *f, const char *fmt, va_list args)
 }
 
 
-/*----------------------------------------------------------------------*/
-/* Reimplement fprintf() as a call to callback function pfcn                     */
-/*----------------------------------------------------------------------*/
+/*----------------------------------------------------------------------
+   Reimplement fprintf() as a call to callback function pfcn
+   via sh_vfprintf, sh_fputs, and sh_fputsll
+  ----------------------------------------------------------------------*/
 
 int
 sh_fprintf(FILE *f, const char *format, ...)
@@ -944,9 +944,10 @@ sh_fprintf(FILE *f, const char *format, ...)
 }
 
 
-/*----------------------------------------------------------------------*/
-/* Reimplement printf() as a call to callback function pfcn                        */
-/*----------------------------------------------------------------------*/
+/*----------------------------------------------------------------------
+   Reimplement printf() as a call to callback function pfcn
+   via sh_vfprintf, sh_fputs, and sh_fputsll
+  ----------------------------------------------------------------------*/
 
 int
 sh_printf(const char *format, ...)
@@ -999,8 +1000,8 @@ static char* outstringerr = NULL;
 static char* outstringout = NULL;
 
 #if defined (low_latency) || !defined(THREADS)
-/* using the strings by the caller sent directly to the caller 
-   has to fast enough (low latency) */
+/* The strings issued by printf etc. are sent directly to the caller. 
+   The callback has to be fast enough (low latency). */
 int
 sh_fputsll(const char *input, FILE* outf)
 {
@@ -1088,7 +1089,8 @@ sh_fputsll(const char *input, FILE* outf)
     return 0;
 }
 
-/* provide a lock around printing function */
+/* provide a lock around printing function.
+   May become critical if latency of callback is too high.*/
 int
 sh_fputs(const char *input, FILE* outf)
 {
@@ -1278,7 +1280,7 @@ char* outstorage(char* wordin, bool write)
 
 
 /* New progress report to statfcn().
-   Update only every DELTATIME milliseconds */
+   An update occurs only every DELTATIME milliseconds. */
 #define DELTATIME 150
 void SetAnalyse( 
    char * Analyse, /*in: analysis type */
@@ -1350,8 +1352,8 @@ void SetAnalyse(
    tfree(s);
 }
 
-/* a dll or shared library should never exit, but ask for graceful shutdown 
-   (e.g. being detached) via a callback function*/
+/* a dll or shared library should never exit, if loaded dynamically, 
+   but ask for graceful shutdown (e.g. being detached) via a callback function*/
 void shared_exit(int status)
 {
     /* alert caller to detach dll (if we are in the main thread),