base/export_template.h

   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 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 // 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  // BASE_EXPORT_TEMPLATE_H_