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