|
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_dlhandle s: 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_remove d, 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.
|