DerelictUtil

Introduction

DerelictUtil contains four modules. Of these, two are intended exlusively for internal use. Of the other two, one, derelict.util.exception, provides optional functionality that the client can use to make an application as robust as possible. The other, derelict.util.loader is primarily intended for internal use but may be useful for anyone needing to manually load a shared library in their application. Regardless of whether or not the client imports any modules from DerelictUtil, the other Derelict packages all have an implicit dependency upon DerelictUtil. As such, when building an application that uses Derelict, the DerelictUtil library must be linked to the application.

The Exception Module

This is the module that will be of most interest to clients. To use this module, you must import derelict.util.exception. It defines three exception types that can be thrown when a shared library fails to load, and also defines the interface for selective symbol loading.

SharedLibLoadException
This exception is thrown when the shared library cannot be loaded. This indicates that the library is not on the user's system, is not on the path, or perhaps has a name that is different than expected. In otherwords, no library could be found that matches the name returned by the sharedLibName property of this exception.

SharedLibProcLoadException
This exception is thrown when a symbol cannot be loaded from a shared library. This might indicate that the library is corrupt, or that it is a different version than expected. In other words, the library exists on the system, but no symbol that matches the name returned by the procName property of this exception could be found. In some cases, it may be desirable to prevent this exception from being thrown. You can learn how by reading about Selective Symbol Loading.

InvalidSharedLibHandleException
This exception might be thrown when attempting to use a handle to a shared library that has already been unloaded. The name of the unloaded library can be retrieved by accessing the sharedLibName property of this exception.

void Derelict_SetMissingProcCallback(MissingProcCallback callback)
[typedef bool function(char[] libName, char[] procName) MissingProcCallback]
This function allows the client to set a callback that will be called when a symbol cannot be found in a shared library. The name of the library will be passed to the callback in the libName parameter and the name of the missing symbol in the procName parameter. The client can use these parameters to determine if Derelict should continue loading the shared library. If so, then the callback should return true. If Derelict should abort loading and throw an exception, the callback should return false. Note that the callback must be set before loading the library(ies) you are interested in. You can read more about this feature in the Selective Symbol Loading documentation.

The Loader Module

derelict.util.loader provides a common interface for Derelict packages to load shared libraries. You should generally only use this module if you are creating a new package for inclusion in Derelict. However, it is useful if you need to load other shared libraries in your Derelict application. Also, DerelictUtil can be used as a standalone package, perhaps as a replacement for std.loader.

SharedLib Derelict_LoadSharedLib(char[] libName)
Opens and returns a shared library handle of type SharedLib. This handle is used by other functions in this module to manipulate the shared library. If the library cannot be loaded, a SharedLibLoadException is thrown.

SharedLib Derelict_LoadSharedLib(char[][] libNames)
Given an array of shared library names, returns a handle to the first shared library successfully loaded. This is intended for use on platforms where a single library may have multiple possible names, such as Linux. The function iterates the array until a successful load. If none of the names result in a successful load, an exception is thrown for the last library name.

void* Derelict_GetProc(SharedLib lib, char[] procName)
Given a handle to a shared library and the name of a symbol, this function loads the symbol from the shared library into memory and returns a pointer to it. This can be used to load exported functions and variables from a shared library. If the symbol cannot be found, this function first checks if a MissingProcCallback has been set and, if so, calls it. Otherwise a SharedLibProcLoadException is thrown. If the shared library referenced by the handle has already been unloaded, an InvalidSharedLibHandleException is thrown.

void Derelict_UnloadSharedLib(SharedLib lib)
Unloads a shared library from memory. The library handle will no longer be valid. Attempts to use it again could cause an InvalidSharedLibHandleException to be thrown. However, if an invalid shared library handle is passed to this function, no exception is thrown and the function is a no-op.