root/branches/Derelict2/doc/util.html

Revision 616, 5.3 kB (checked in by aldacron, 4 months ago)

[Derelict2]
* updated mime-type on all the documentation

  • Property svn:mime-type set to text/html
Line 
1 <html lang="en">
2 <head>
3     <title>DerelictUtil Package</title>
4     <link rel="stylesheet" type="text/css" href="styles.css">
5 </head>
6 <body>
7 <h2>DerelictUtil</h2>
8 DerelictUtil contains several modules. Of these, two are intended exclusively for
9 internal use. Of the remainder, one, <tt>derelict.util.exception</tt>, provides
10 optional functionality that the client can use to make an application as robust
11 as possible. <tt>derelict.util.loader</tt> and <tt>derelict.util.sharedlib</tt>
12 are primarily intended for internal use but may be useful for anyone needing to
13 manually load a shared library in their applications. Finally, <tt>derelict.util.compat</tt>
14 is also primarily intended for internal use, but can be used outside of Derelict
15 to facilitate interoperability between D1/D2 and Phobos/Tango. Regardless of whether or not
16 the client imports any modules from DerelictUtil, the other Derelict packages all
17 have an implicit dependency upon the package. As such, when building an application
18 that uses Derelict, the DerelictUtil library <em>must</em> be linked with the executable.
19
20 <h3>The Exception Module</h3>
21 This is the module that will be of most interest to clients. To use this module,
22 you must import <tt>derelict.util.exception</tt>. It defines two exception types
23 that can be thrown when a shared library fails to load, and also defines the
24 interface for <a href="selective.html">selective symbol loading</a>. Both
25 exception types share a common base class, <tt>DerelictException</tt>.
26
27 <p>
28 <tt>SharedLibLoadException</tt><br>
29 This exception is thrown when the shared library cannot be loaded. This indicates
30 that the library is not on the user's system, is not on the path, or perhaps has
31 a name that is different than expected. In other words, no library could be found
32 that matches the name returned by the <tt>sharedLibName</tt> property of this
33 exception.
34 </p>
35 <p>
36 These exceptions may be chained in cases where Derelict attempts to load a library
37 using multiple names. An exception will be created for each failure and chained to
38 the last created exception. If the library fails to load after all of the names
39 have been attempted, then the last exception created will be thrown with all
40 of the previous exceptions chained to it.
41 </p>
42
43 <p><tt>SymbolLoadException</tt><br>
44 This exception is thrown when a symbol cannot be loaded from a shared library.
45 This might indicate that the library is corrupt, or that it is a different version
46 than expected. In other words, the library exists on the system, but
47 no symbol could be found that matches the name returned by the <tt>symbolName</tt> property of
48 this exception. In some cases, it may be desirable to prevent this exception from being
49 thrown. You can learn how by reading about <a href="selective.html">Selective Symbol Loading</a>.
50 </p>
51
52 <p><tt>void Derelict_SetMissingSymbolCallback(MissingSymbolCallback callback)</tt></br>
53 <tt><b>[alias bool function(char[] libName, char[] symbolName) MissingSymbolCallback]</b></tt><br>
54 This function allows the client to set a callback that will be called when a
55 symbol cannot be found in a shared library. The name of the library will be passed
56 to the callback in the <tt>libName</tt> parameter and the name of the missing
57 symbol in the <tt>symbolName</tt> parameter. The client can use these parameters
58 to determine if Derelict should continue loading the shared library. If so, then
59 the callback should return true. If Derelict should abort loading and throw an exception,
60 the callback should return false. Note that the callback must be set before loading
61 the library(ies) you are interested in. You can read more about this feature in
62 the <a href="selective.html">Selective Symbol Loading</a> documentation.
63 </p>
64
65 <h3><a class="bookmark" name="Loader">The Loader Module</a></h3>
66 In this module, you will find the class <tt>SharedLibLoader</tt>. This is the base class
67 of all package-specific loaders in Derelict. For normal use of Derelict, you need not
68 concern yourself with this class. However, there is one specific use case where it may
69 come in handy.
70
71 <p>
72 By default, each shared library in Derelict is unloaded in a module destructor at program
73 exit. This means you need not call the <tt>unload</tt> method on any loader yourself. However,
74 conflicts can sometimes arise when you want to use Derelict with your own resource management
75 scheme. In these rare cases, it's possible that your code may try call a function through one
76 of Derelict's function pointers after a library has already been unloaded. For those situations,
77 <tt>SharedLibLoader</tt> exposes a static method that disables automatic unloading of shared
78 libraries. Once this method is called, it is the client's responsibility to call the unload
79 method on any loader whose load method was successfully called.
80 </p>
81 <p>
82 The following code example shows how to use this feature.
83 </p>
84
85 <pre>
86 // First, you must make sure to import derelict.util.loader.
87 import derelict.util.loader;
88
89 // In a function or method, make the following call.
90 SharedLibLoader.disableAutoUnload();
91
92 // From this point on, you are responsible for calling
93 // unload on any loader objects whose load methods were
94 // successfully called before or after disableAutoUnload.
95 // Derelict will not unload *any* shared libraries at all.
96 </pre>
97
98 </body>
99 </html>
Note: See TracBrowser for help on using the browser.