mdempsky | fba51c1 | 2016-02-09 14:41:47 +0900 | [diff] [blame] | 1 | // Copyright 2015 The Chromium Authors. All rights reserved. |
| 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 IPC_EXPORT_TEMPLATE_H_ |
| 6 | #define IPC_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 | // The implementation of this header uses some subtle macro semantics to |
| 30 | // detect what the provided FOO_EXPORT value was defined as and then |
| 31 | // to dispatch to appropriate macro definitions. Unfortunately, |
| 32 | // MSVC's C preprocessor is rather non-compliant and requires special |
| 33 | // care to make it work. |
| 34 | // |
| 35 | // Issue 1. |
| 36 | // |
| 37 | // #define F(x) |
| 38 | // F() |
| 39 | // |
| 40 | // MSVC emits warning C4003 ("not enough actual parameters for macro |
| 41 | // 'F'), even though it's a valid macro invocation. This affects the |
| 42 | // macros below that take just an "export" parameter, because export |
| 43 | // may be empty. |
| 44 | // |
| 45 | // As a workaround, we can add a dummy parameter and arguments: |
| 46 | // |
| 47 | // #define F(x,_) |
| 48 | // F(,) |
| 49 | // |
| 50 | // Issue 2. |
| 51 | // |
| 52 | // #define F(x) G##x |
| 53 | // #define Gj() ok |
| 54 | // F(j()) |
| 55 | // |
| 56 | // The correct replacement for "F(j())" is "ok", but MSVC replaces it |
| 57 | // with "Gj()". As a workaround, we can pass the result to an |
| 58 | // identity macro to force MSVC to look for replacements again. (This |
| 59 | // is why EXPORT_TEMPLATE_STYLE_3 exists.) |
| 60 | |
| 61 | #define EXPORT_TEMPLATE_DECLARE(export) \ |
| 62 | EXPORT_TEMPLATE_INVOKE(DECLARE, EXPORT_TEMPLATE_STYLE(export, ), export) |
| 63 | #define EXPORT_TEMPLATE_DEFINE(export) \ |
| 64 | EXPORT_TEMPLATE_INVOKE(DEFINE, EXPORT_TEMPLATE_STYLE(export, ), export) |
| 65 | |
| 66 | // INVOKE is an internal helper macro to perform parameter replacements |
| 67 | // and token pasting to chain invoke another macro. E.g., |
| 68 | // EXPORT_TEMPLATE_INVOKE(DECLARE, DEFAULT, FOO_EXPORT) |
| 69 | // will export to call |
| 70 | // EXPORT_TEMPLATE_DECLARE_DEFAULT(FOO_EXPORT, ) |
| 71 | // (but with FOO_EXPORT expanded too). |
| 72 | #define EXPORT_TEMPLATE_INVOKE(which, style, export) \ |
| 73 | EXPORT_TEMPLATE_INVOKE_2(which, style, export) |
| 74 | #define EXPORT_TEMPLATE_INVOKE_2(which, style, export) \ |
| 75 | EXPORT_TEMPLATE_##which##_##style(export, ) |
| 76 | |
| 77 | // Default style is to apply the FOO_EXPORT macro at declaration sites. |
| 78 | #define EXPORT_TEMPLATE_DECLARE_DEFAULT(export, _) export |
| 79 | #define EXPORT_TEMPLATE_DEFINE_DEFAULT(export, _) |
| 80 | |
| 81 | // The "MSVC hack" style is used when FOO_EXPORT is defined |
| 82 | // as __declspec(dllexport), which MSVC requires to be used at |
| 83 | // definition sites instead. |
| 84 | #define EXPORT_TEMPLATE_DECLARE_MSVC_HACK(export, _) |
| 85 | #define EXPORT_TEMPLATE_DEFINE_MSVC_HACK(export, _) export |
| 86 | |
| 87 | // EXPORT_TEMPLATE_STYLE is an internal helper macro that identifies which |
| 88 | // export style needs to be used for the provided FOO_EXPORT macro definition. |
| 89 | // "", "__attribute__(...)", and "__declspec(dllimport)" are mapped |
| 90 | // to "DEFAULT"; while "__declspec(dllexport)" is mapped to "MSVC_HACK". |
| 91 | // |
| 92 | // It's implemented with token pasting to transform the __attribute__ and |
| 93 | // __declspec annotations into macro invocations. E.g., if FOO_EXPORT is |
| 94 | // defined as "__declspec(dllimport)", it undergoes the following sequence of |
| 95 | // macro substitutions: |
| 96 | // EXPORT_TEMPLATE_STYLE(FOO_EXPORT, ) |
| 97 | // EXPORT_TEMPLATE_STYLE_2(__declspec(dllimport), ) |
| 98 | // EXPORT_TEMPLATE_STYLE_3(EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport)) |
| 99 | // EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport) |
| 100 | // EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport |
| 101 | // DEFAULT |
| 102 | #define EXPORT_TEMPLATE_STYLE(export, _) EXPORT_TEMPLATE_STYLE_2(export, ) |
| 103 | #define EXPORT_TEMPLATE_STYLE_2(export, _) \ |
| 104 | EXPORT_TEMPLATE_STYLE_3( \ |
| 105 | EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA##export) |
| 106 | #define EXPORT_TEMPLATE_STYLE_3(style) style |
| 107 | |
| 108 | // Internal helper macros for EXPORT_TEMPLATE_STYLE. |
| 109 | // |
| 110 | // XXX: C++ reserves all identifiers containing "__" for the implementation, |
| 111 | // but "__attribute__" and "__declspec" already contain "__" and the token-paste |
| 112 | // operator can only add characters; not remove them. To minimize the risk of |
| 113 | // conflict with implementations, we include "foj3FJo5StF0OvIzl7oMxA" (a random |
| 114 | // 128-bit string, encoded in Base64) in the macro name. |
| 115 | #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA DEFAULT |
| 116 | #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__attribute__(...) \ |
| 117 | DEFAULT |
| 118 | #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__declspec(arg) \ |
| 119 | EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_##arg |
| 120 | |
| 121 | // Internal helper macros for EXPORT_TEMPLATE_STYLE. |
| 122 | #define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllexport MSVC_HACK |
| 123 | #define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport DEFAULT |
| 124 | |
| 125 | // Sanity checks. |
| 126 | // |
| 127 | // EXPORT_TEMPLATE_TEST uses the same macro invocation pattern as |
| 128 | // EXPORT_TEMPLATE_DECLARE and EXPORT_TEMPLATE_DEFINE do to check that they're |
| 129 | // working correctly. When they're working correctly, the sequence of macro |
| 130 | // replacements should go something like: |
| 131 | // |
| 132 | // EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); |
| 133 | // |
| 134 | // static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, |
| 135 | // EXPORT_TEMPLATE_STYLE(__declspec(dllimport), ), |
| 136 | // __declspec(dllimport)), "__declspec(dllimport)"); |
| 137 | // |
| 138 | // static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, |
| 139 | // DEFAULT, __declspec(dllimport)), "__declspec(dllimport)"); |
| 140 | // |
| 141 | // static_assert(EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT( |
| 142 | // __declspec(dllimport)), "__declspec(dllimport)"); |
| 143 | // |
| 144 | // static_assert(true, "__declspec(dllimport)"); |
| 145 | // |
| 146 | // When they're not working correctly, a syntax error should occur instead. |
| 147 | #define EXPORT_TEMPLATE_TEST(want, export) \ |
| 148 | static_assert(EXPORT_TEMPLATE_INVOKE( \ |
| 149 | TEST_##want, EXPORT_TEMPLATE_STYLE(export, ), export), \ |
| 150 | #export) |
| 151 | #define EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT(...) true |
| 152 | #define EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK(...) true |
| 153 | |
| 154 | EXPORT_TEMPLATE_TEST(DEFAULT, ); |
| 155 | EXPORT_TEMPLATE_TEST(DEFAULT, __attribute__((visibility("default")))); |
| 156 | EXPORT_TEMPLATE_TEST(MSVC_HACK, __declspec(dllexport)); |
| 157 | EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); |
| 158 | |
| 159 | #undef EXPORT_TEMPLATE_TEST |
| 160 | #undef EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT |
| 161 | #undef EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK |
| 162 | |
| 163 | #endif // IPC_EXPORT_TEMPLATE_H_ |