1 /* 2 * Copyright (c) 2019 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef RTC_BASE_SYSTEM_RTC_EXPORT_TEMPLATE_H_ 12 #define RTC_BASE_SYSTEM_RTC_EXPORT_TEMPLATE_H_ 13 14 // clang-format off 15 // clang formating would cause cpplint errors in the macros below. 16 17 // Most of this was borrowed (with minor modifications) from Chromium's 18 // base/export_template.h. 19 20 // Synopsis 21 // 22 // This header provides macros for using RTC_EXPORT macros with explicit 23 // template instantiation declarations and definitions. 24 // Generally, the RTC_EXPORT macros are used at declarations, 25 // and GCC requires them to be used at explicit instantiation declarations, 26 // but MSVC requires __declspec(dllexport) to be used at the explicit 27 // instantiation definitions instead. 28 29 // Usage 30 // 31 // In a header file, write: 32 // 33 // extern template class RTC_EXPORT_TEMPLATE_DECLARE(RTC_EXPORT) foo<bar>; 34 // 35 // In a source file, write: 36 // 37 // template class RTC_EXPORT_TEMPLATE_DEFINE(RTC_EXPORT) foo<bar>; 38 39 // Implementation notes 40 // 41 // On Windows, when building when RTC_EXPORT expands to __declspec(dllexport)), 42 // we want the two lines to expand to: 43 // 44 // extern template class foo<bar>; 45 // template class RTC_EXPORT foo<bar>; 46 // 47 // In all other cases (non-Windows, and Windows when RTC_EXPORT expands to 48 // __declspec(dllimport)), we want: 49 // 50 // extern template class RTC_EXPORT foo<bar>; 51 // template class foo<bar>; 52 // 53 // The implementation of this header uses some subtle macro semantics to 54 // detect what the provided RTC_EXPORT value was defined as and then 55 // to dispatch to appropriate macro definitions. Unfortunately, 56 // MSVC's C preprocessor is rather non-compliant and requires special 57 // care to make it work. 58 // 59 // Issue 1. 60 // 61 // #define F(x) 62 // F() 63 // 64 // MSVC emits warning C4003 ("not enough actual parameters for macro 65 // 'F'), even though it's a valid macro invocation. This affects the 66 // macros below that take just an "export" parameter, because export 67 // may be empty. 68 // 69 // As a workaround, we can add a dummy parameter and arguments: 70 // 71 // #define F(x,_) 72 // F(,) 73 // 74 // Issue 2. 75 // 76 // #define F(x) G##x 77 // #define Gj() ok 78 // F(j()) 79 // 80 // The correct replacement for "F(j())" is "ok", but MSVC replaces it 81 // with "Gj()". As a workaround, we can pass the result to an 82 // identity macro to force MSVC to look for replacements again. (This 83 // is why RTC_EXPORT_TEMPLATE_STYLE_3 exists.) 84 85 #define RTC_EXPORT_TEMPLATE_DECLARE(export) \ 86 RTC_EXPORT_TEMPLATE_INVOKE( \ 87 DECLARE, \ 88 RTC_EXPORT_TEMPLATE_STYLE(export, ), export) // NOLINT 89 #define RTC_EXPORT_TEMPLATE_DEFINE(export) \ 90 RTC_EXPORT_TEMPLATE_INVOKE( \ 91 DEFINE, \ 92 RTC_EXPORT_TEMPLATE_STYLE(export, ), export) // NOLINT 93 94 // INVOKE is an internal helper macro to perform parameter replacements 95 // and token pasting to chain invoke another macro. E.g., 96 // RTC_EXPORT_TEMPLATE_INVOKE(DECLARE, DEFAULT, RTC_EXPORT) 97 // will export to call 98 // RTC_EXPORT_TEMPLATE_DECLARE_DEFAULT(RTC_EXPORT, ) 99 // (but with RTC_EXPORT expanded too). 100 #define RTC_EXPORT_TEMPLATE_INVOKE(which, style, export) \ 101 RTC_EXPORT_TEMPLATE_INVOKE_2(which, style, export) 102 #define RTC_EXPORT_TEMPLATE_INVOKE_2(which, style, export) \ 103 RTC_EXPORT_TEMPLATE_##which##_##style(export, ) 104 105 // Default style is to apply the RTC_EXPORT macro at declaration sites. 106 #define RTC_EXPORT_TEMPLATE_DECLARE_DEFAULT(export, _) export 107 #define RTC_EXPORT_TEMPLATE_DEFINE_DEFAULT(export, _) 108 109 // The "MSVC hack" style is used when RTC_EXPORT is defined 110 // as __declspec(dllexport), which MSVC requires to be used at 111 // definition sites instead. 112 #define RTC_EXPORT_TEMPLATE_DECLARE_MSVC_HACK(export, _) 113 #define RTC_EXPORT_TEMPLATE_DEFINE_MSVC_HACK(export, _) export 114 115 // RTC_EXPORT_TEMPLATE_STYLE is an internal helper macro that identifies which 116 // export style needs to be used for the provided RTC_EXPORT macro definition. 117 // "", "__attribute__(...)", and "__declspec(dllimport)" are mapped 118 // to "DEFAULT"; while "__declspec(dllexport)" is mapped to "MSVC_HACK". 119 // 120 // It's implemented with token pasting to transform the __attribute__ and 121 // __declspec annotations into macro invocations. E.g., if RTC_EXPORT is 122 // defined as "__declspec(dllimport)", it undergoes the following sequence of 123 // macro substitutions: 124 // RTC_EXPORT_TEMPLATE_STYLE(RTC_EXPORT,) 125 // RTC_EXPORT_TEMPLATE_STYLE_2(__declspec(dllimport),) 126 // RTC_EXPORT_TEMPLATE_STYLE_3( 127 // RTC_EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport)) 128 // RTC_EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport) 129 // RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport 130 // DEFAULT 131 #define RTC_EXPORT_TEMPLATE_STYLE(export, _) \ 132 RTC_EXPORT_TEMPLATE_STYLE_2(export, ) 133 #define RTC_EXPORT_TEMPLATE_STYLE_2(export, _) \ 134 RTC_EXPORT_TEMPLATE_STYLE_3( \ 135 RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA##export) 136 #define RTC_EXPORT_TEMPLATE_STYLE_3(style) style 137 138 // Internal helper macros for RTC_EXPORT_TEMPLATE_STYLE. 139 // 140 // XXX: C++ reserves all identifiers containing "__" for the implementation, 141 // but "__attribute__" and "__declspec" already contain "__" and the token-paste 142 // operator can only add characters; not remove them. To minimize the risk of 143 // conflict with implementations, we include "foj3FJo5StF0OvIzl7oMxA" (a random 144 // 128-bit string, encoded in Base64) in the macro name. 145 #define RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA DEFAULT 146 #define RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__attribute__( \ 147 ...) \ 148 DEFAULT 149 #define RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__declspec(arg) \ 150 RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_##arg 151 152 // Internal helper macros for RTC_EXPORT_TEMPLATE_STYLE. 153 #define RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllexport MSVC_HACK 154 #define RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport DEFAULT 155 156 // Sanity checks. 157 // 158 // RTC_EXPORT_TEMPLATE_TEST uses the same macro invocation pattern as 159 // RTC_EXPORT_TEMPLATE_DECLARE and RTC_EXPORT_TEMPLATE_DEFINE do to check that 160 // they're working correctly. When they're working correctly, the sequence of 161 // macro replacements should go something like: 162 // 163 // RTC_EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); 164 // 165 // static_assert(RTC_EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, 166 // RTC_EXPORT_TEMPLATE_STYLE(__declspec(dllimport), ), 167 // __declspec(dllimport)), "__declspec(dllimport)"); 168 // 169 // static_assert(RTC_EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, 170 // DEFAULT, __declspec(dllimport)), "__declspec(dllimport)"); 171 // 172 // static_assert(RTC_EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT( 173 // __declspec(dllimport)), "__declspec(dllimport)"); 174 // 175 // static_assert(true, "__declspec(dllimport)"); 176 // 177 // When they're not working correctly, a syntax error should occur instead. 178 #define RTC_EXPORT_TEMPLATE_TEST(want, export) \ 179 static_assert( \ 180 RTC_EXPORT_TEMPLATE_INVOKE( \ 181 TEST_##want, \ 182 RTC_EXPORT_TEMPLATE_STYLE(export, ), export), #export) // NOLINT 183 #define RTC_EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT(...) true 184 #define RTC_EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK(...) true 185 186 RTC_EXPORT_TEMPLATE_TEST(DEFAULT, ); // NOLINT 187 RTC_EXPORT_TEMPLATE_TEST(DEFAULT, __attribute__((visibility("default")))); 188 RTC_EXPORT_TEMPLATE_TEST(MSVC_HACK, __declspec(dllexport)); 189 RTC_EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); 190 191 #undef RTC_EXPORT_TEMPLATE_TEST 192 #undef RTC_EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT 193 #undef RTC_EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK 194 195 // clang-format on 196 197 #endif // RTC_BASE_SYSTEM_RTC_EXPORT_TEMPLATE_H_ 198