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