18.5.2 Loader Management

The API supplies all of the functions you need to implement your own module loading mechanisms to solve problems just like this:

Function: lt_dlloader_t * lt_dlloader_find (const char *loader_name)

Each of the module loaders implemented by libltdl is stored according to a unique name, which can be used to lookup the associated handle. These handles operate in much the same way as lt_dlhandles: They are used for passing references to modules in and out of the API, except that they represent a kind of module loading method, as opposed to a loaded module instance.

This function finds the `lt_dlloader_t' handle associated with the unique name passed as the only argument, or else returns `NULL' if there is no such module loader registered.

Function: int lt_dlloader_add (lt_dlloader_t *place, lt_user_dlloader *dlloader, const char *loader_name)

This function is used to register your own module loading mechanisms with libltdl. If place is given it must be a handle for an already registered module loader, which the new loader dlloader will be placed in front of for the purposes of which order to try loaders in. If place is `NULL', on the other hand, the new dlloader will be added to the end of the list of loaders to try when loading a module instance. In either case loader_name must be a unique name for use with lt_dlloader_find.

The dlloader argument must be a C structure of the following format, populated with suitable function pointers which determine the functionality of your module loader:

struct lt_user_dlloader { const char *sym_prefix; lt_module_open_t *module_open; lt_module_close_t *module_close; lt_find_sym_t *find_sym; lt_dlloader_exit_t *dlloader_exit; lt_dlloader_data_t dlloader_data; };

Function: int lt_dlloader_remove (const char *loader_name)

When there are no more loaded modules that were opened by the given module loader, the loader itself can be removed using this function.

When you come to set the fields in the lt_user_dlloader structure, they must each be of the correct type, as described below:

Type: const char * sym_prefix

If a particular module loader relies on a prefix to each symbol being looked up (for example, the Windows module loader necessarily adds a `_' prefix to each symbol name passed to lt_dlsym), it should be recorded in the `sym_prefix' field.

Type: lt_module_t lt_module_open_t (lt_dlloader_data_t loader_data, const char *module_name)

When lt_dlopen has reached your registered module loader when attempting to load a dynamic module, this is the type of the module_open function that will be called. The name of the module that libltdl is attempting to load, along with the module loader instance data associated with the loader being used currently, are passed as arguments to such a function call.

The lt_module_t returned by functions of this type can be anything at all that can be recognised as unique to a successfully loaded module instance when passed back into the module_close or find_sym functions in the lt_user_dlloader module loader structure.

Type: int lt_module_close_t (lt_dlloader_data_t loader_data, lt_module_t module)

In a similar vein, a function of this type will be called by lt_dlclose, where module is the returned value from the `module_open' function which loaded this dynamic module instance.

Type: lt_ptr_t lt_find_sym_t (lt_dlloader_data_t loader_data, lt_module_t module, const char *symbol_name)

In a similar vein once more, a function of this type will be called by lt_dlsym, and must return the address of symbol_name in module.

Type: int lt_dlloader_exit_t (lt_dlloader_data_t loader_data)

When a user module loader is lt_dlloader_removed, a function of this type will be called. That function is responsible for releasing any resources that were allocated during the initialisation of the loader, so that they are not `leaked' when the lt_user_dlloader structure is recycled.

Note that there is no initialisation function type: the initialisation of a user module loader should be performed before the loader is registered with lt_dlloader_add.

Type: lt_dlloader_data_t dlloader_data

The dlloader_data is a spare field which can be used to store or pass any data specific to a particular module loader. That data will always be passed as the value of the first argument to each of the implementation functions above.