The C function
QuitLispWorks
allows a LispWorks dynamic library to be unloaded. You should make a LispWorks dynamic library 'quit' by calling
QuitLispWorks
before unloading the library. This call causes LispWorks to cleanup everything it uses, in particular the memory and threads.
In general,
QuitLispWorks
should be called only when the LispWorks dynamic library is idle. That is, when there is no callback into the library that has not returned, and there are no processes that has started by a callback. All callbacks should return, and any processes should be killed before calling
QuitLispWorks
.
Force should be 0 or 1. It specifies whether to force quitting even if LispWorks is still executing something.
MilliTimeOut specifies how long to wait for LispWorks to complete the cleanup.
If LispWorks is idle,
QuitLispWorks
signals it to quit, and waits
MilliTimeOut
milliseconds for it to finish the cleanup. If LispWorks finished cleanup,
QuitLispWorks
return 0 (SUCCESS). If the cleanup is not finished it returns -2 (TIMEOUT).
If LispWorks is not idle, that is there are still some active callbacks or there are processes that have started by a callback (even if they are inside process-wait),
QuitLispWorks
checks the value of
Force
. If
Force
is 0,
QuitLispWorks
returns -1 (NOT_IDLE). If
Force
is 1,
QuitLispWorks
signals it to quit and behaves as if LispWorks is idle, described above.
QuitLispWorks
can be called repeatedly to check if LispWorks finished the cleanup.
When
QuitLispWorks
returns NOT_IDLE, it has done nothing, and the LispWorks dynamic library can be used for further callbacks. Once
QuitLispWorks
returns any other value, callbacks into the dynamic library will result in undefined behavior.
Once
QuitLispWorks
returns SUCCESS, it is safe to unload the dynamic library. Unloading it before
QuitLispWorks
returns SUCCESS gives undefined results.
Once
QuitLispWorks
returns SUCCESS, LispWorks can be initialized again. Calling any exported function (supplied to save-image or deliver in
dll-exports
) or any of InitLispWorks, SimpleInitLispWorks and LispWorksDlsym will cause LispWorks to initialize again.
Note: On Linux, Macintosh and FreeBSD it is possible to add calls to
QuitLispWorks
at the right places via
dll-added-files
.
Note: A possible reason for failure to finish the cleanup is that a LispWorks process is stuck inside a foreign call. Dynamic library applications that need to be unloaded should be careful to ensure that they do not get stuck in a foreign function call.
QuitLispWorks
is defined in each LispWorks dynamic library. For information about creating a LispWorks dynamic library, see deliver and save-image. For an overview of LispWorks as a dynamic library, see the section "LispWorks as a dynamic library" in the
LispWorks User Guide
.