1 // Copyright 2015 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_EXPORT_TEMPLATE_H_ 6 #define BASE_EXPORT_TEMPLATE_H_ 7 8 // Synopsis 9 // 10 // This header provides macros for using FOO_EXPORT macros with explicit 11 // template instantiation declarations and definitions. 12 // Generally, the FOO_EXPORT macros are used at declarations, 13 // and GCC requires them to be used at explicit instantiation declarations, 14 // but MSVC requires __declspec(dllexport) to be used at the explicit 15 // instantiation definitions instead. 16 17 // Usage 18 // 19 // In a header file, write: 20 // 21 // extern template class EXPORT_TEMPLATE_DECLARE(FOO_EXPORT) foo<bar>; 22 // 23 // In a source file, write: 24 // 25 // template class EXPORT_TEMPLATE_DEFINE(FOO_EXPORT) foo<bar>; 26 27 // Implementation notes 28 // 29 // On Windows, when building the FOO library (that is, when FOO_EXPORT expands 30 // to __declspec(dllexport)), we want the two lines to expand to: 31 // 32 // extern template class foo<bar>; 33 // template class FOO_EXPORT foo<bar>; 34 // 35 // In all other cases (non-Windows, and Windows when using the FOO library (that 36 // is when FOO_EXPORT expands to __declspec(dllimport)), we want: 37 // 38 // extern template class FOO_EXPORT foo<bar>; 39 // template class foo<bar>; 40 // 41 // The implementation of this header uses some subtle macro semantics to 42 // detect what the provided FOO_EXPORT value was defined as and then 43 // to dispatch to appropriate macro definitions. 44 45 #define EXPORT_TEMPLATE_DECLARE(foo_export) \ 46 EXPORT_TEMPLATE_INVOKE(DECLARE, EXPORT_TEMPLATE_STYLE(foo_export), foo_export) 47 #define EXPORT_TEMPLATE_DEFINE(foo_export) \ 48 EXPORT_TEMPLATE_INVOKE(DEFINE, EXPORT_TEMPLATE_STYLE(foo_export), foo_export) 49 50 // INVOKE is an internal helper macro to perform parameter replacements 51 // and token pasting to chain invoke another macro. E.g., 52 // EXPORT_TEMPLATE_INVOKE(DECLARE, DEFAULT, FOO_EXPORT) 53 // will expand to call 54 // EXPORT_TEMPLATE_DECLARE_DEFAULT(FOO_EXPORT) 55 // (but with FOO_EXPORT expanded too). 56 #define EXPORT_TEMPLATE_INVOKE(which, style, foo_export) \ 57 EXPORT_TEMPLATE_INVOKE_2(which, style, foo_export) 58 #define EXPORT_TEMPLATE_INVOKE_2(which, style, foo_export) \ 59 EXPORT_TEMPLATE_##which##_##style(foo_export) 60 61 // Default style is to apply the FOO_EXPORT macro at declaration sites. 62 #define EXPORT_TEMPLATE_DECLARE_DEFAULT(foo_export) foo_export 63 #define EXPORT_TEMPLATE_DEFINE_DEFAULT(foo_export) 64 65 // The "declspec" style is used when FOO_EXPORT is defined 66 // as __declspec(dllexport), which MSVC requires to be used at 67 // definition sites instead. 68 #define EXPORT_TEMPLATE_DECLARE_EXPORT_DLLEXPORT(foo_export) 69 #define EXPORT_TEMPLATE_DEFINE_EXPORT_DLLEXPORT(foo_export) foo_export 70 71 // EXPORT_TEMPLATE_STYLE is an internal helper macro that identifies which 72 // export style needs to be used for the provided FOO_EXPORT macro definition. 73 // "", "__attribute__(...)", and "__declspec(dllimport)" are mapped 74 // to "DEFAULT"; while "__declspec(dllexport)" is mapped to "EXPORT_DLLEXPORT". 75 // (NaCl headers define "DLLEXPORT" already, else we'd use that. 76 // TODO(thakis): Rename once nacl is gone.) 77 // 78 // It's implemented with token pasting to transform the __attribute__ and 79 // __declspec annotations into macro invocations. E.g., if FOO_EXPORT is 80 // defined as "__declspec(dllimport)", it undergoes the following sequence of 81 // macro substitutions: 82 // EXPORT_TEMPLATE_STYLE(FOO_EXPORT) 83 // EXPORT_TEMPLATE_STYLE_2(__declspec(dllimport)) 84 // EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport) 85 // EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport 86 // DEFAULT 87 #define EXPORT_TEMPLATE_STYLE(foo_export) EXPORT_TEMPLATE_STYLE_2(foo_export) 88 #define EXPORT_TEMPLATE_STYLE_2(foo_export) \ 89 EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA##foo_export 90 91 // Internal helper macros for EXPORT_TEMPLATE_STYLE. 92 // 93 // XXX: C++ reserves all identifiers containing "__" for the implementation, 94 // but "__attribute__" and "__declspec" already contain "__" and the token-paste 95 // operator can only add characters; not remove them. To minimize the risk of 96 // conflict with implementations, we include "foj3FJo5StF0OvIzl7oMxA" (a random 97 // 128-bit string, encoded in Base64) in the macro name. 98 #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA DEFAULT 99 #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__attribute__(...) \ 100 DEFAULT 101 #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__declspec(arg) \ 102 EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_##arg 103 104 // Internal helper macros for EXPORT_TEMPLATE_STYLE. 105 #define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllexport EXPORT_DLLEXPORT 106 #define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport DEFAULT 107 108 // Sanity checks. 109 // 110 // EXPORT_TEMPLATE_TEST uses the same macro invocation pattern as 111 // EXPORT_TEMPLATE_DECLARE and EXPORT_TEMPLATE_DEFINE do to check that they're 112 // working correctly. When they're working correctly, the sequence of macro 113 // replacements should go something like: 114 // 115 // EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); 116 // 117 // static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, 118 // EXPORT_TEMPLATE_STYLE(__declspec(dllimport)), 119 // __declspec(dllimport)), "__declspec(dllimport)"); 120 // 121 // static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, 122 // DEFAULT, __declspec(dllimport)), "__declspec(dllimport)"); 123 // 124 // static_assert(EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT( 125 // __declspec(dllimport)), "__declspec(dllimport)"); 126 // 127 // static_assert(true, "__declspec(dllimport)"); 128 // 129 // When they're not working correctly, a syntax error should occur instead. 130 #define EXPORT_TEMPLATE_TEST(want, foo_export) \ 131 static_assert( \ 132 EXPORT_TEMPLATE_INVOKE(TEST_##want, EXPORT_TEMPLATE_STYLE(foo_export), \ 133 foo_export), \ 134 #foo_export) 135 #define EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT(...) true 136 #define EXPORT_TEMPLATE_TEST_EXPORT_DLLEXPORT_EXPORT_DLLEXPORT(...) true 137 138 EXPORT_TEMPLATE_TEST(DEFAULT, ); 139 EXPORT_TEMPLATE_TEST(DEFAULT, __attribute__((visibility("default")))); 140 EXPORT_TEMPLATE_TEST(EXPORT_DLLEXPORT, __declspec(dllexport)); 141 EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); 142 143 #undef EXPORT_TEMPLATE_TEST 144 #undef EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT 145 #undef EXPORT_TEMPLATE_TEST_EXPORT_DLLEXPORT_EXPORT_DLLEXPORT 146 147 #endif // BASE_EXPORT_TEMPLATE_H_ 148