C function

Summary

Allows a LispWorks dynamic library to be unloaded.

Signature

On Windows:

int __stdcall QuitLispWorks(int Force, int MilliTimeOut)

On Linux, Macintosh, FreeBSD and x86/x64 Solaris:

int QuitLispWorks(int Force, int MilliTimeOut)

Description

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 whether 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, FreeBSD and x86/x64 Solaris 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 LispWorks as a dynamic library.

See also

deliver
dll-quit
save-image