Libraries: 3 The Library Entry Point

LibraryEntry(), LibraryCallType

A library may need to do bookkeeping when it is launched, when a client is attached, or at other times. For this reason, some libraries will have an entry point routine. The entry point routine is called by the kernel; it should never be called by other geodes. Some of the calls are made in the kernel thread, while others are made by a geode's thread. All of the calls are made automatically by the kernel.

An entry point routine must take two arguments. The format of an entry point is shown in A Library Entry Point .

Code Display C-1 A Library Entry Point

Boolean _pascal
	LibraryEntry(LibraryCallType				ty,
			GeodeHandle		client);

When the kernel calls the entry point routine, it passes the following arguments:

A member of the LibraryCallType enumerated type. This specifies why the kernel is calling the routine. This type is described below.
A geode handle. This parameter is valid only if certain LibraryCallType values are passed.

The entry point should return true if an error occurs; otherwise it should return false (i.e. zero).

LibraryCallType contains the following members:

LCT_ATTACH: This is passed when the library has just been launched. The client parameter is undefined. The call is made in the application's thread.
LCT_DETACH: This is passed when the library is about to be unloaded. The client parameter is undefined. The call is made in the application's thread.
LCT_NEW_CLIENT: A thread has just called GeodeUseLibrary() , or a geode which depends on the library is being launched. The client parameter contains the GeodeHandle of the new client. The call is made in the kernel thread.
LCT_NEW_CLIENT_THREAD: A geode which depends on the library has just spawned a new thread. The client parameter contains the GeodeHandle of the thread's owner. The call is made in the new thread.
LCT_CLIENT_THREAD_EXIT: A thread which uses the library is being destroyed. The client parameter contains the GeodeHandle of the thread's owner. The call is made in the soon-to-be destroyed thread.
LCT_CLIENT_EXIT: A client loaded this library with GeodeUseLibrary() has just called GeodeFreeLibrary() . The client parameter contains the GeodeHandle of the former client. The call is made in the kernel thread.

Sometimes a single action can prompt several calls to the entry point, each with a different LibraryCallType value. For example, suppose FooWrite is launched. This application's .gp file specifies that it uses the BarObj library. At the time FooWrite is launched, BarObj has not been loaded. The kernel will automatically launch BarObj and immediately call the entry point with parameter LCT_ATTACH. The kernel will then call the entry point again with parameter LCT_NEW_CLIENT, passing FooWrite's GeodeHandle . It will then call the entry point once for each FooWrite thread, passing LCT_NEW_CLIENT_THREAD; it will make these calls as each thread is started.

Some libraries will not need to take any actions when the entry point is called; these libraries need not have an entry point routine. On the other hand, some libraries will need to do bookkeeping chores. This is left entirely to the library's discretion.

The entry point should take care not to perform any actions with side effects outside the library. If the entry point allocates memory, it should make sure to make the library's geode the block's owner. Similarly, the entry point should not change the working directory; instead, it should use FilePushDir() and FilePopDir() to make temporary changes to the working directory.

GEOS SDK TechDocs |

2 Library Basics | Next:

4 Exported Routines and Classes