// Copyright 2017 the V8 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.

#ifndef V8_BASE_EXPORT_TEMPLATE_H_

#define V8_BASE_EXPORT_TEMPLATE_H_

// Synopsis

//

// This header provides macros for using FOO_EXPORT macros with explicit

// template instantiation declarations and definitions.

// Generally, the FOO_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 EXPORT_TEMPLATE_DECLARE(FOO_EXPORT) foo<bar>;

//

// In a source file, write:

//

// template class EXPORT_TEMPLATE_DEFINE(FOO_EXPORT) foo<bar>;

// Implementation notes

//

// The implementation of this header uses some subtle macro semantics to

// detect what the provided FOO_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 EXPORT_TEMPLATE_STYLE_3 exists.)

#define EXPORT_TEMPLATE_DECLARE(export) \

EXPORT_TEMPLATE_INVOKE(DECLARE, EXPORT_TEMPLATE_STYLE(export, ), export)

#define EXPORT_TEMPLATE_DEFINE(export) \

EXPORT_TEMPLATE_INVOKE(DEFINE, EXPORT_TEMPLATE_STYLE(export, ), export)

// INVOKE is an internal helper macro to perform parameter replacements

// and token pasting to chain invoke another macro. E.g.,

// EXPORT_TEMPLATE_INVOKE(DECLARE, DEFAULT, FOO_EXPORT)

// will export to call

// EXPORT_TEMPLATE_DECLARE_DEFAULT(FOO_EXPORT, )

// (but with FOO_EXPORT expanded too).

#define EXPORT_TEMPLATE_INVOKE(which, style, export) \

EXPORT_TEMPLATE_INVOKE_2(which, style, export)

#define EXPORT_TEMPLATE_INVOKE_2(which, style, export) \

EXPORT_TEMPLATE_##which##_##style(export, )

// Default style is to apply the FOO_EXPORT macro at declaration sites.

#define EXPORT_TEMPLATE_DECLARE_DEFAULT(export, _) export

#define EXPORT_TEMPLATE_DEFINE_DEFAULT(export, _)

// The "MSVC hack" style is used when FOO_EXPORT is defined

// as __declspec(dllexport), which MSVC requires to be used at

// definition sites instead.

#define EXPORT_TEMPLATE_DECLARE_MSVC_HACK(export, _)

#define EXPORT_TEMPLATE_DEFINE_MSVC_HACK(export, _) export

// EXPORT_TEMPLATE_STYLE is an internal helper macro that identifies which

// export style needs to be used for the provided FOO_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 FOO_EXPORT is

// defined as "__declspec(dllimport)", it undergoes the following sequence of

// macro substitutions:

// EXPORT_TEMPLATE_STYLE(FOO_EXPORT, )

// EXPORT_TEMPLATE_STYLE_2(__declspec(dllimport), )

// EXPORT_TEMPLATE_STYLE_3(EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport))

// EXPORT_TEMPLATE_STYLE_MATCH__declspec(dllimport)

// EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport

// DEFAULT

#define EXPORT_TEMPLATE_STYLE(export, _) EXPORT_TEMPLATE_STYLE_2(export, )

#define EXPORT_TEMPLATE_STYLE_2(export, _) \

EXPORT_TEMPLATE_STYLE_3( \

EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA##export)

#define EXPORT_TEMPLATE_STYLE_3(style) style

// Internal helper macros for 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 EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA DEFAULT

#define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__attribute__(...) \

DEFAULT

#define EXPORT_TEMPLATE_STYLE_MATCH_foj3FJo5StF0OvIzl7oMxA__declspec(arg) \

EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_##arg

// Internal helper macros for EXPORT_TEMPLATE_STYLE.

#define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllexport MSVC_HACK

#define EXPORT_TEMPLATE_STYLE_MATCH_DECLSPEC_dllimport DEFAULT

// Sanity checks.

//

// EXPORT_TEMPLATE_TEST uses the same macro invocation pattern as

// EXPORT_TEMPLATE_DECLARE and 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:

//

// EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport));

//

// static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT,

// EXPORT_TEMPLATE_STYLE(__declspec(dllimport), ),

// __declspec(dllimport)), "__declspec(dllimport)");

//

// static_assert(EXPORT_TEMPLATE_INVOKE(TEST_DEFAULT,

// DEFAULT, __declspec(dllimport)), "__declspec(dllimport)");

//

// static_assert(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 EXPORT_TEMPLATE_TEST(want, export) \

static_assert(EXPORT_TEMPLATE_INVOKE( \

TEST_##want, EXPORT_TEMPLATE_STYLE(export, ), export), \

#export)

#define EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT(...) true

#define EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK(...) true

EXPORT_TEMPLATE_TEST(DEFAULT, );

EXPORT_TEMPLATE_TEST(DEFAULT, __attribute__((visibility("default"))));

EXPORT_TEMPLATE_TEST(MSVC_HACK, __declspec(dllexport));

EXPORT_TEMPLATE_TEST(DEFAULT, __declspec(dllimport));

#undef EXPORT_TEMPLATE_TEST

#undef EXPORT_TEMPLATE_TEST_DEFAULT_DEFAULT

#undef EXPORT_TEMPLATE_TEST_MSVC_HACK_MSVC_HACK

#endif // V8_BASE_EXPORT_TEMPLATE_H_