export_template.h 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147
  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. #ifndef BASE_EXPORT_TEMPLATE_H_
  5. #define BASE_EXPORT_TEMPLATE_H_
  6. // Synopsis
  7. //
  8. // This header provides macros for using FOO_EXPORT macros with explicit
  9. // template instantiation declarations and definitions.
  10. // Generally, the FOO_EXPORT macros are used at declarations,
  11. // and GCC requires them to be used at explicit instantiation declarations,
  12. // but MSVC requires __declspec(dllexport) to be used at the explicit
  13. // instantiation definitions instead.
  14. // Usage
  15. //
  16. // In a header file, write:
  17. //
  18. // extern template class EXPORT_TEMPLATE_DECLARE(FOO_EXPORT) foo<bar>;
  19. //
  20. // In a source file, write:
  21. //
  22. // template class EXPORT_TEMPLATE_DEFINE(FOO_EXPORT) foo<bar>;
  23. // Implementation notes
  24. //
  25. // On Windows, when building the FOO library (that is, when FOO_EXPORT expands
  26. // to __declspec(dllexport)), we want the two lines to expand to:
  27. //
  28. // extern template class foo<bar>;
  29. // template class FOO_EXPORT foo<bar>;
  30. //
  31. // In all other cases (non-Windows, and Windows when using the FOO library (that
  32. // is when FOO_EXPORT expands to __declspec(dllimport)), we want:
  33. //
  34. // extern template class FOO_EXPORT foo<bar>;
  35. // template class foo<bar>;
  36. //
  37. // The implementation of this header uses some subtle macro semantics to
  38. // detect what the provided FOO_EXPORT value was defined as and then
  39. // to dispatch to appropriate macro definitions.
  40. #define EXPORT_TEMPLATE_DECLARE(foo_export) \
  41. EXPORT_TEMPLATE_INVOKE(DECLARE, EXPORT_TEMPLATE_STYLE(foo_export), foo_export)
  42. #define EXPORT_TEMPLATE_DEFINE(foo_export) \
  43. EXPORT_TEMPLATE_INVOKE(DEFINE, EXPORT_TEMPLATE_STYLE(foo_export), foo_export)
  44. // INVOKE is an internal helper macro to perform parameter replacements
  45. // and token pasting to chain invoke another macro. E.g.,
  46. // EXPORT_TEMPLATE_INVOKE(DECLARE, DEFAULT, FOO_EXPORT)
  47. // will expand to call
  48. // EXPORT_TEMPLATE_DECLARE_DEFAULT(FOO_EXPORT)
  49. // (but with FOO_EXPORT expanded too).
  50. #define EXPORT_TEMPLATE_INVOKE(which, style, foo_export) \
  51. EXPORT_TEMPLATE_INVOKE_2(which, style, foo_export)
  52. #define EXPORT_TEMPLATE_INVOKE_2(which, style, foo_export) \
  53. EXPORT_TEMPLATE_##which##_##style(foo_export)
  54. // Default style is to apply the FOO_EXPORT macro at declaration sites.
  55. #define EXPORT_TEMPLATE_DECLARE_DEFAULT(foo_export) foo_export
  56. #define EXPORT_TEMPLATE_DEFINE_DEFAULT(foo_export)
  57. // The "declspec" style is used when FOO_EXPORT is defined
  58. // as __declspec(dllexport), which MSVC requires to be used at
  59. // definition sites instead.
  60. #define EXPORT_TEMPLATE_DECLARE_EXPORT_DLLEXPORT(foo_export)
  61. #define EXPORT_TEMPLATE_DEFINE_EXPORT_DLLEXPORT(foo_export) foo_export
  62. // EXPORT_TEMPLATE_STYLE is an internal helper macro that identifies which
  63. // export style needs to be used for the provided FOO_EXPORT macro definition.
  64. // "", "__attribute__(...)", and "__declspec(dllimport)" are mapped
  65. // to "DEFAULT"; while "__declspec(dllexport)" is mapped to "EXPORT_DLLEXPORT".
  66. // (NaCl headers define "DLLEXPORT" already, else we'd use that.
  67. // TODO(thakis): Rename once nacl is gone.)
  68. //
  69. // It's implemented with token pasting to transform the __attribute__ and
  70. // __declspec annotations into macro invocations. E.g., if FOO_EXPORT is
  71. // defined as "__declspec(dllimport)", it undergoes the following sequence of
  72. // macro substitutions:
  73. // EXPORT_TEMPLATE_STYLE(FOO_EXPORT)
  74. // EXPORT_TEMPLATE_STYLE_2(__declspec(dllimport))
  75. // EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport)
  76. // EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport
  77. // DEFAULT
  78. #define EXPORT_TEMPLATE_STYLE(foo_export) EXPORT_TEMPLATE_STYLE_2(foo_export)
  79. #define EXPORT_TEMPLATE_STYLE_2(foo_export) \
  80. EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA##foo_export
  81. // Internal helper macros for EXPORT_TEMPLATE_STYLE.
  82. //
  83. // XXX: C++ reserves all identifiers containing "__" for the implementation,
  84. // but "__attribute__" and "__declspec" already contain "__" and the token-paste
  85. // operator can only add characters; not remove them. To minimize the risk of
  86. // conflict with implementations, we include "foj3FJo5StF0OvIzl7oMxA" (a random
  87. // 128-bit string, encoded in Base64) in the macro name.
  88. #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA DEFAULT
  89. #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__attribute__(...) \
  90. DEFAULT
  91. #define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__declspec(arg) \
  92. EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_##arg
  93. // Internal helper macros for EXPORT_TEMPLATE_STYLE.
  94. #define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllexport EXPORT_DLLEXPORT
  95. #define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport DEFAULT
  96. // Sanity checks.
  97. //
  98. // EXPORT_TEMPLATE_TEST uses the same macro invocation pattern as
  99. // EXPORT_TEMPLATE_DECLARE and EXPORT_TEMPLATE_DEFINE do to check that they're
  100. // working correctly. When they're working correctly, the sequence of macro
  101. // replacements should go something like:
  102. //
  103. // EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport));
  104. //
  105. // static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT,
  106. // EXPORT_TEMPLATE_STYLE(__declspec(dllimport)),
  107. // __declspec(dllimport)), "__declspec(dllimport)");
  108. //
  109. // static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT,
  110. // DEFAULT, __declspec(dllimport)), "__declspec(dllimport)");
  111. //
  112. // static_assert(EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT(
  113. // __declspec(dllimport)), "__declspec(dllimport)");
  114. //
  115. // static_assert(true, "__declspec(dllimport)");
  116. //
  117. // When they're not working correctly, a syntax error should occur instead.
  118. #define EXPORT_TEMPLATE_TEST(want, foo_export) \
  119. static_assert( \
  120. EXPORT_TEMPLATE_INVOKE(TEST_##want, EXPORT_TEMPLATE_STYLE(foo_export), \
  121. foo_export), \
  122. #foo_export)
  123. #define EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT(...) true
  124. #define EXPORT_TEMPLATE_TEST_EXPORT_DLLEXPORT_EXPORT_DLLEXPORT(...) true
  125. EXPORT_TEMPLATE_TEST(DEFAULT, );
  126. EXPORT_TEMPLATE_TEST(DEFAULT, __attribute__((visibility("default"))));
  127. EXPORT_TEMPLATE_TEST(EXPORT_DLLEXPORT, __declspec(dllexport));
  128. EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport));
  129. #undef EXPORT_TEMPLATE_TEST
  130. #undef EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT
  131. #undef EXPORT_TEMPLATE_TEST_EXPORT_DLLEXPORT_EXPORT_DLLEXPORT
  132. #endif // BASE_EXPORT_TEMPLATE_H_