V8 API Reference, 7.2.502.16 (for Deno 0.2.4)
export-template.h
1 // Copyright 2017 the V8 project 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 V8_BASE_EXPORT_TEMPLATE_H_
6 #define V8_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 // 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 // V8_BASE_EXPORT_TEMPLATE_H_