From b54605c22538ba60a4f87f6bc39e3229a42ce8fd Mon Sep 17 00:00:00 2001 From: h_vogt Date: Fri, 12 Apr 2013 23:59:27 +0200 Subject: [PATCH] sharedspice.c: improved comments --- src/sharedspice.c | 55 +++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/src/sharedspice.c b/src/sharedspice.c index 7be9dae42..b8763bcc1 100644 --- a/src/sharedspice.c +++ b/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),