C function

Summary

Provides control over the initialization of a LispWorks dynamic library.

Signature

On Windows:

int __stdcall InitLispWorks (int MilliTimeOut , void * BaseAddress , size_t ReserveSize )

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

int InitLispWorks (int MilliTimeOut , void * BaseAddress , size_t ReserveSize )

Description

The C function InitLispWorks allows you to relocate a LispWorks dynamic library if this is necessary, and offers control of the initialization process.

A LispWorks dynamic library is automatically initialized by any call to its exported symbols, so in most cases there is no need to call InitLispWorks . It is however necessary when you need to relocate LispWorks or when you need finer control over the initialization process.

For more information about relocating a LispWorks dynamic library, see Startup relocation)

MilliTimeOut specifies the time in milliseconds to wait for LispWorks to finish initializing before returning. InitLispWorks checks whether the library was initialized and if not initiates initialization. It then waits at most MilliTimeOut milliseconds before returning.

BaseAddress specifies the base address for relocation. Can be 0.

ReserveSize specifies the reserve size for relocation. Can be 0.

BaseAddress and ReserveSize are interpreted as described in Startup relocation.

Non-negative return values indicate success:

1

LispWorks was already initialized or in the process of initializing, and finished initializing by the time InitLispWorks returned.

0

InitLispWorks initialized LispWorks and the initialization finished successfully.

Values in the inclusive range [-1, -99] indicate a timeout:

-1

InitLispWorks started initialization and timed out before LispWorks finished mapping itself from the file.

-2

LispWorks already started initialization, and InitLispWorks timed out before LispWorks finished mapping itself from the file.

-3

InitLispWorks started initialization and timed out after LispWorks mapped itself from the file, but before the initialization was complete.

-4

LispWorks already started initialization, and InitLispWorks timed out before after LispWorks mapped itself from the file, but before the initialization was complete.

After InitLispWorks times out, the state of LispWorks can be queried by LispWorksState.

Lower values indicate failure, as follows:

-1000

Failure to start a thread to do the initialization.

-1401

The file seems to be corrupted.

-1402

Failure to map into memory.

-1403

Failure to read the LispWorks header from the file.

-1406

Bad base address.

Additionally, a value value in the inclusive range [-1400, -1001] on Linux, Macintosh, FreeBSD and x86/x64 Solaris platforms indicates an error in a system call. Calculate the errno number by -1001 - value .

Note: If LispWorks is already initialized or in the process of being initialized, InitLispWorks does not initiate the process of initialization. Therefore the arguments to InitLispWorks have no effect if LispWorks was already initialized when it is called. On Microsoft Windows, the default behavior is to initialize a LispWorks dynamic library automatically during loading, so this needs to be disabled to use InitLispWorks effectively. Disable automatic initialization of a library as described for deliver and save-image.

Note: Once QuitLispWorks has returned 0, LispWorks can be initialized again. It is possible to quit and restart LispWorks several times, at the same address or at a different address.

Note: On Linux, Macintosh, FreeBSD and x86/x64 Solaris you can create wrappers to the C functions described in this chapter from your application by writing them in C and adding them to the dynamic library using dll-added-files in deliver and save-image . Such wrappers can be used to add calls to InitLispWorks before actually calling into Lisp.

InitLispWorks 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
LispWorksState
save-image
QuitLispWorks