1 /* 2 3 Boost Software License - Version 1.0 - August 17th, 2003 4 5 Permission is hereby granted, free of charge, to any person or organization 6 obtaining a copy of the software and accompanying documentation covered by 7 this license (the "Software") to use, reproduce, display, distribute, 8 execute, and transmit the Software, and to prepare derivative works of the 9 Software, and to permit third-parties to whom the Software is furnished to 10 do so, all subject to the following: 11 12 The copyright notices in the Software and this entire statement, including 13 the above license grant, this restriction and the following disclaimer, 14 must be included in all copies of the Software, in whole or in part, and 15 all derivative works of the Software, unless such copies or derivative 16 works are solely in the form of machine-executable object code generated by 17 a source language processor. 18 19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT 22 SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE 23 FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, 24 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 DEALINGS IN THE SOFTWARE. 26 27 */ 28 module derelict.util.exception; 29 30 /++ 31 Base class for all exceptions thrown by Derelict packages. 32 +/ 33 class DerelictException : Exception { 34 public this(string msg, size_t line = __LINE__, string file = __FILE__) { 35 super(msg, file, line, null); 36 } 37 } 38 39 /++ 40 Helper struct to facilitate throwing a single SharedLibException after failing 41 to load a library using multiple names. 42 +/ 43 private struct FailedSharedLib { 44 string name; 45 string reason; 46 } 47 48 /++ 49 This exception is thrown when a shared library cannot be loaded 50 because it is either missing or not on the system path. 51 +/ 52 class SharedLibLoadException : DerelictException 53 { 54 private string _sharedLibName; 55 56 public { 57 static void throwNew(string[] libNames, string[] reasons, size_t line = __LINE__, string file = __FILE__) { 58 string msg = "Failed to load one or more shared libraries:"; 59 foreach(i, n; libNames) { 60 msg ~= "\n\t" ~ n ~ " - "; 61 if(i < reasons.length) 62 msg ~= reasons[i]; 63 else 64 msg ~= "Unknown"; 65 } 66 throw new SharedLibLoadException(msg, line, file); 67 } 68 69 this(string msg, size_t line = __LINE__, string file = __FILE__) { 70 super(msg, line, file); 71 _sharedLibName = ""; 72 } 73 74 this(string msg, string sharedLibName, size_t line = __LINE__, string file = __FILE__) { 75 super(msg, line, file); 76 _sharedLibName = sharedLibName; 77 } 78 79 string sharedLibName() { 80 return _sharedLibName; 81 } 82 } 83 } 84 85 /++ 86 This exception is thrown when a symbol cannot be loaded from a shared library, 87 either because it does not exist in the library or because the library is corrupt. 88 +/ 89 class SymbolLoadException : DerelictException 90 { 91 private string _symbolName; 92 93 public { 94 this(string msg, size_t line = __LINE__, string file = __FILE__) { 95 super(msg, line, file); 96 } 97 98 this(string sharedLibName, string symbolName, size_t line = __LINE__, string file = __FILE__) { 99 super("Failed to load symbol " ~ symbolName ~ " from shared library " ~ sharedLibName, line, file); 100 _symbolName = symbolName; 101 } 102 103 string symbolName() { 104 return _symbolName; 105 } 106 } 107 } 108 109 /++ 110 The return type of the MissingSymbolCallbackFunc/Dg. 111 +/ 112 enum ShouldThrow { 113 No, 114 Yes 115 } 116 117 /++ 118 The MissingSymbolCallback allows the user to prevent the throwing of SymbolLoadExceptions. 119 120 By default, a SymbolLoadException is thrown when a symbol cannot be found in a shared 121 library. Assigning a MissingSymbolCallback to a loader allows the application to override 122 this behavior. If the missing symbol in question can be ignored, the callback should 123 return ShouldThrow.No to prevent the exception from being thrown. Otherwise, the 124 return value should be ShouldThrow.Yes. This is useful to allow a binding implemented 125 for version N.N of a library to load older or newer versions that may be missing 126 functions the loader expects to find, provided of course that the app does not need 127 to use those functions. 128 +/ 129 alias MissingSymbolCallbackFunc = ShouldThrow function(string symbolName); 130 /// Ditto 131 alias MissingSymbolCallbackDg = ShouldThrow delegate(string symbolName); 132 133 /// Convenient alias to use as a return value. 134 alias MissingSymbolCallback = MissingSymbolCallbackDg;