sharedspice.c: improved comments

src/sharedspice.c

@@ -16,8 +16,10 @@
 #define STDERR_FILENO   2
 #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
 
 /**********************************************************************/
@@ -280,6 +282,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)
 {
@@ -305,7 +308,7 @@ _thread_run(void *string)
 }
 
 
-/*Stops a running thread, hopefully */
+/* Stops a running background thread, hopefully */
 static int EXPORT_FLAVOR
 _thread_stop(void)
 {
@@ -356,6 +359,7 @@ sighandler_sharedspice(int num)
 #endif /*THREADS*/
 
 
+/* run a ngspice command */
 static int
 runc(char* command)
 {
@@ -463,7 +467,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)
@@ -473,7 +477,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,
@@ -656,7 +660,6 @@ IMPEXP
 int  ngSpice_Command(char* comexec)
 {
     if ( ! setjmp(errbufc) ) {
-//       HANDLE tid2;
 
         immediate = FALSE;
         intermj = 1;
@@ -665,12 +668,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;
     }
@@ -807,8 +807,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)
@@ -887,7 +887,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 */
 
@@ -901,9 +901,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, ...)
@@ -919,9 +920,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, ...)
@@ -975,8 +977,8 @@ 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)
 {
@@ -1064,7 +1066,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)
 {
@@ -1254,7 +1257,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 */
@@ -1326,8 +1329,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),