Libraries: 2 Library Basics

A library is a geode, much like an application geode. However, its behavior is slightly different. In particular, libraries do not have any threads of their own, unless they explicitly create them.

When a geode calls a routine which is exported from a library, the routine is run by the thread which made the call, not by the library's thread. This has several implications. First, it means that a library's response time is not dependent on the number of applications which use the library. An application which uses the library a lot will do so on its own time and may have its priority reduced accordingly. Indeed, a library with many users is likely to perform better than one with few users, since its code will be less likely to be swapped out of the global heap. Similarly, library routines will use the stack of the calling thread; this means that the same routine can be called by several different threads at once, with less danger of a synchronization problem.

Another consequence is that if a library routine allocates memory, that memory will belong to the owning geode. Thus, when the application exits, the memory will automatically be freed; on the other hand, if the library exits before the application does, the memory block will remain. If a library wants to have the block owned by the library geode, it must set the owner explicitly.

Geodes which use a library are said to be its "clients." A client may declare that it uses a library in its .gp file, or it may load the library at runtime by calling GeodeUseLibrary() . One library may be a client of another; in this case, when the first library is loaded, the second will be as well.

A library may have a single special routine, known as its entry point . The kernel calls this routine to inform the library when it is launched or freed, when it acquires a new client, or when a client is unloaded. The entry point routine is described more fully in The Library Entry Point .

A library may export object classes or routines. If a routine is exported, it may be called by any geode which uses the library. If an object class is exported, any geode which uses the library may instantiate objects of that class, and may define a subclass of it.

Every library should have a library header file. This header file contains declarations for all exported routines and classes, as well as definitions of any appropriate macros, constants, structures, etc. Every geode which uses the library will need to include this header file. If the library exports any object classes, the header file should be a Goc header file with the suffix .goh ; otherwise it should be a standard C header file with the suffix .h . The header file is described in more detail in Header Files .

GEOS SDK TechDocs |

1 Design Philosophy | Next:

3 The Library Entry Point