Function

Summary

Makes a LispWorks dynamic library quit.

Package

lispworks

Signature

dll-quit &key kill-all-processes timeout output force => result, quit-output

Arguments

kill-all-processes

A generalized boolean.

timeout

A positive integer or nil.

output

An output stream designator.

force

A generalized boolean.

Values

result

t or nil.

quit-output

A string or nil.

Description

The function dll-quit makes a LispWorks dynamic library (or DLL) quit on returning from the callback in which it was called. It must be called only:

• In an image running as a dynamic library, meaning an image created by save-image with :dll-exports or by deliver with :dll-exports, and
• Inside the dynamic scope of a callback into the dynamic library. That is, not in a process that was started by process-run-function.

dll-quit sets up the internal state such that just before returning into its caller in the LispWorks dynamic library it causes LispWorks to quit. After quitting the callback returns as normal. The library can be unloaded using FreeLibrary, or you can re-use it (without re-loading).

By default kill-all-processes is nil which means that, if there are other running processes, dll-quit just returns nil. If kill-all-processes is non-nil, dll-quit tries to kill all the other processes, and if it succeeds, it quits.

If kill-all-processes is true, timeout is a maximum time to wait after killing the other processes. It allows timeout seconds for all processes to die.

dll-quit should be called when no other processes are running, whether they were created by a callback or by process-run-function. If such processes exist, by default dll-quit does nothing and returns nil. If force is non-nil, dll-quit always tries to set LispWorks up for quitting. LispWorks will quit even after a failure to kill all other processes and complete any required shut down operations. A true value of force automatically implies kill-all-processes true. However, if any of the other processes is stuck in a foreign call, the quitting may fail to finish properly. The default value of force is nil.

If output is supplied, dll-quit generates output if it is called when other processes are still running, or a required shut down operation was not completed. output can be an output stream, t (interpreted as *standard-output*) or nil. If output is nil, dll-quit collects the output and returns it as second argument quit-output. Otherwise it writes the output to the stream and quit-output is nil.

The output contains a list of the other processes that are still running. If kill-all-processes or force was supplied, and killing the other processes failed, the output also contains backtraces of the other processes, and possibly other debugging information.

result is t on success: the LispWorks dynamic library is set to quit on returning from the callback. result is nil when other processes are running: the image is not set to quit.

quit-output contains the output which was generated when output nil was passed. Otherwise quit-output is nil.

If dll-quit is called inside a recursive foreign callback, the LispWorks dynamic library quits only when the outermost callback returns.

Notes

1. dll-quit is intended for use when a LispWorks dynamic library is loaded by a main process which you (the LispWorks programmer) do not control. If you control the main process, then use QuitLispWorks instead.

It is expected that the main process will call into the dynamic library with some "shutdown" call, and then calls FreeLibrary to free the library. The shutdown call should close and free everything that needs to be closed or freed, call dll-quit, and return.

2. dll-quit is supported only where LispWorks can be a dynamic library. Currently this is in 32-bit LispWorks on Microsoft Windows, Intel Macintosh, Linux, x86/x64 Solaris and FreeBSD, and in 64-bit LispWorks on Windows, Intel Macintosh, Linux and x86/x64 Solaris.

See also

deliver
save-image