diff --git a/rtc_base/system/BUILD.gn b/rtc_base/system/BUILD.gn index 4c2b5cd50a..8b78e347e2 100644 --- a/rtc_base/system/BUILD.gn +++ b/rtc_base/system/BUILD.gn @@ -63,6 +63,7 @@ rtc_source_set("unused") { rtc_source_set("rtc_export") { sources = [ "rtc_export.h", + "rtc_export_template.h", ] } diff --git a/rtc_base/system/rtc_export_template.h b/rtc_base/system/rtc_export_template.h new file mode 100644 index 0000000000..4ac7043835 --- /dev/null +++ b/rtc_base/system/rtc_export_template.h @@ -0,0 +1,197 @@ +/* + * Copyright (c) 2019 The WebRTC project authors. All Rights Reserved. + * + * Use of this source code is governed by a BSD-style license + * that can be found in the LICENSE file in the root of the source + * tree. An additional intellectual property rights grant can be found + * in the file PATENTS. All contributing project authors may + * be found in the AUTHORS file in the root of the source tree. + */ + +#ifndef RTC_BASE_SYSTEM_RTC_EXPORT_TEMPLATE_H_ +#define RTC_BASE_SYSTEM_RTC_EXPORT_TEMPLATE_H_ + +// clang-format off +// clang formating would cause cpplint errors in the macros below. + +// Most of this was borrowed (with minor modifications) from Chromium's +// base/export_template.h. + +// Synopsis +// +// This header provides macros for using RTC_EXPORT macros with explicit +// template instantiation declarations and definitions. +// Generally, the RTC_EXPORT macros are used at declarations, +// and GCC requires them to be used at explicit instantiation declarations, +// but MSVC requires __declspec(dllexport) to be used at the explicit +// instantiation definitions instead. + +// Usage +// +// In a header file, write: +// +// extern template class RTC_EXPORT_TEMPLATE_DECLARE(RTC_EXPORT) foo; +// +// In a source file, write: +// +// template class RTC_EXPORT_TEMPLATE_DEFINE(RTC_EXPORT) foo; + +// Implementation notes +// +// On Windows, when building when RTC_EXPORT expands to __declspec(dllexport)), +// we want the two lines to expand to: +// +// extern template class foo; +// template class RTC_EXPORT foo; +// +// In all other cases (non-Windows, and Windows when RTC_EXPORT expands to +// __declspec(dllimport)), we want: +// +// extern template class RTC_EXPORT foo; +// template class foo; +// +// The implementation of this header uses some subtle macro semantics to +// detect what the provided RTC_EXPORT value was defined as and then +// to dispatch to appropriate macro definitions. Unfortunately, +// MSVC's C preprocessor is rather non-compliant and requires special +// care to make it work. +// +// Issue 1. +// +// #define F(x) +// F() +// +// MSVC emits warning C4003 ("not enough actual parameters for macro +// 'F'), even though it's a valid macro invocation. This affects the +// macros below that take just an "export" parameter, because export +// may be empty. +// +// As a workaround, we can add a dummy parameter and arguments: +// +// #define F(x,_) +// F(,) +// +// Issue 2. +// +// #define F(x) G##x +// #define Gj() ok +// F(j()) +// +// The correct replacement for "F(j())" is "ok", but MSVC replaces it +// with "Gj()". As a workaround, we can pass the result to an +// identity macro to force MSVC to look for replacements again. (This +// is why RTC_EXPORT_TEMPLATE_STYLE_3 exists.) + +#define RTC_EXPORT_TEMPLATE_DECLARE(export) \ + RTC_EXPORT_TEMPLATE_INVOKE( \ + DECLARE, \ + RTC_EXPORT_TEMPLATE_STYLE(export, ), export) // NOLINT +#define RTC_EXPORT_TEMPLATE_DEFINE(export) \ + RTC_EXPORT_TEMPLATE_INVOKE( \ + DEFINE, \ + RTC_EXPORT_TEMPLATE_STYLE(export, ), export) // NOLINT + +// INVOKE is an internal helper macro to perform parameter replacements +// and token pasting to chain invoke another macro. E.g., +// RTC_EXPORT_TEMPLATE_INVOKE(DECLARE, DEFAULT, RTC_EXPORT) +// will export to call +// RTC_EXPORT_TEMPLATE_DECLARE_DEFAULT(RTC_EXPORT, ) +// (but with RTC_EXPORT expanded too). +#define RTC_EXPORT_TEMPLATE_INVOKE(which, style, export) \ + RTC_EXPORT_TEMPLATE_INVOKE_2(which, style, export) +#define RTC_EXPORT_TEMPLATE_INVOKE_2(which, style, export) \ + RTC_EXPORT_TEMPLATE_##which##_##style(export, ) + +// Default style is to apply the RTC_EXPORT macro at declaration sites. +#define RTC_EXPORT_TEMPLATE_DECLARE_DEFAULT(export, _) export +#define RTC_EXPORT_TEMPLATE_DEFINE_DEFAULT(export, _) + +// The "MSVC hack" style is used when RTC_EXPORT is defined +// as __declspec(dllexport), which MSVC requires to be used at +// definition sites instead. +#define RTC_EXPORT_TEMPLATE_DECLARE_MSVC_HACK(export, _) +#define RTC_EXPORT_TEMPLATE_DEFINE_MSVC_HACK(export, _) export + +// RTC_EXPORT_TEMPLATE_STYLE is an internal helper macro that identifies which +// export style needs to be used for the provided RTC_EXPORT macro definition. +// "", "__attribute__(...)", and "__declspec(dllimport)" are mapped +// to "DEFAULT"; while "__declspec(dllexport)" is mapped to "MSVC_HACK". +// +// It's implemented with token pasting to transform the __attribute__ and +// __declspec annotations into macro invocations. E.g., if RTC_EXPORT is +// defined as "__declspec(dllimport)", it undergoes the following sequence of +// macro substitutions: +// RTC_EXPORT_TEMPLATE_STYLE(RTC_EXPORT,) +// RTC_EXPORT_TEMPLATE_STYLE_2(__declspec(dllimport),) +// RTC_EXPORT_TEMPLATE_STYLE_3( +// RTC_EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport)) +// RTC_EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport) +// RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport +// DEFAULT +#define RTC_EXPORT_TEMPLATE_STYLE(export, _) \ + RTC_EXPORT_TEMPLATE_STYLE_2(export, ) +#define RTC_EXPORT_TEMPLATE_STYLE_2(export, _) \ + RTC_EXPORT_TEMPLATE_STYLE_3( \ + RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA##export) +#define RTC_EXPORT_TEMPLATE_STYLE_3(style) style + +// Internal helper macros for RTC_EXPORT_TEMPLATE_STYLE. +// +// XXX: C++ reserves all identifiers containing "__" for the implementation, +// but "__attribute__" and "__declspec" already contain "__" and the token-paste +// operator can only add characters; not remove them. To minimize the risk of +// conflict with implementations, we include "foj3FJo5StF0OvIzl7oMxA" (a random +// 128-bit string, encoded in Base64) in the macro name. +#define RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA DEFAULT +#define RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__attribute__( \ + ...) \ + DEFAULT +#define RTC_EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__declspec(arg) \ + RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_##arg + +// Internal helper macros for RTC_EXPORT_TEMPLATE_STYLE. +#define RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllexport MSVC_HACK +#define RTC_EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport DEFAULT + +// Sanity checks. +// +// RTC_EXPORT_TEMPLATE_TEST uses the same macro invocation pattern as +// RTC_EXPORT_TEMPLATE_DECLARE and RTC_EXPORT_TEMPLATE_DEFINE do to check that +// they're working correctly. When they're working correctly, the sequence of +// macro replacements should go something like: +// +// RTC_EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); +// +// static_assert(RTC_EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, +// RTC_EXPORT_TEMPLATE_STYLE(__declspec(dllimport), ), +// __declspec(dllimport)), "__declspec(dllimport)"); +// +// static_assert(RTC_EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT, +// DEFAULT, __declspec(dllimport)), "__declspec(dllimport)"); +// +// static_assert(RTC_EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT( +// __declspec(dllimport)), "__declspec(dllimport)"); +// +// static_assert(true, "__declspec(dllimport)"); +// +// When they're not working correctly, a syntax error should occur instead. +#define RTC_EXPORT_TEMPLATE_TEST(want, export) \ + static_assert( \ + RTC_EXPORT_TEMPLATE_INVOKE( \ + TEST_##want, \ + RTC_EXPORT_TEMPLATE_STYLE(export, ), export), #export) // NOLINT +#define RTC_EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT(...) true +#define RTC_EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK(...) true + +RTC_EXPORT_TEMPLATE_TEST(DEFAULT, ); // NOLINT +RTC_EXPORT_TEMPLATE_TEST(DEFAULT, __attribute__((visibility("default")))); +RTC_EXPORT_TEMPLATE_TEST(MSVC_HACK, __declspec(dllexport)); +RTC_EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport)); + +#undef RTC_EXPORT_TEMPLATE_TEST +#undef RTC_EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT +#undef RTC_EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK + +// clang-format on + +#endif // RTC_BASE_SYSTEM_RTC_EXPORT_TEMPLATE_H_