support/annotations.h - third_party/github.com/google/crubit - Git at Google


            
            // Part of the Crubit project, under the Apache License v2.0 with LLVM

            
            // Exceptions. See /LICENSE for license information.

            
            // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception


            // IWYU pragma: private, include "support/annotations.h"


            #ifndef THIRD_PARTY_CRUBIT_SUPPORT_ANNOTATIONS_H_

            
            #define THIRD_PARTY_CRUBIT_SUPPORT_ANNOTATIONS_H_


            #include "support/annotations_internal.h"


            // SWIG does not follow `#include` directives, so it cannot see the definitions

            
            // below and reports "Syntax error in input" when it parses a header that uses

            
            // these annotations. To make SWIG treat them as no-ops, add

            
            // `%include "support/annotations.swig"` to the `.swig` file

            
            // (after `%include "base/swig/google.swig"`), and add

            
            // `//support:annotations_swig` to the SWIG rule's

            
            // `swig_includes`. See b/566029265.


            // Marks a function or type as requiring Rust binding.

            
            //

            
            // If Crubit fails to generate bindings for a function or type annotated with

            
            // `CRUBIT_MUST_BIND`, bindings generation for the entire target will fail

            
            // with a hard error.

            
            //

            
            // This can be useful when developing C++ API surfaces that are intended to be

            
            // used from Rust, as it produces a clear error message when a function is

            
            // missing bindings.

            
            //

            
            // For example, this C++ header will silently not produce bindings for

            
            // `foo` because overloads are not supported.

            
            //

            
            // ```c++

            
            // void foo();

            
            // void foo(int x);

            
            // void bar();

            
            // ```

            
            //

            
            // This default behavior allows `bar` to still receive bindings.

            
            //

            
            // By contrast, this C++ header will fail at binding generation time with an

            
            // error message describing that overloads are not supported:

            
            //

            
            // ```c++

            
            // CRUBIT_MUST_BIND void foo();

            
            // void foo(int x);

            
            // void bar();

            
            // ```

            
            //

            
            // The annotation can also be applied to a type:

            
            //

            
            // ```c++

            
            // struct CRUBIT_MUST_BIND Foo {

            
            //   int x;

            
            // };

            
            // ```

            
            #define CRUBIT_MUST_BIND CRUBIT_INTERNAL_ANNOTATE("crubit_must_bind")


            // Prevents a function or type from receiving Rust bindings.

            
            //

            
            // Use of this annotation should be avoided where-possible as usage of it can

            
            // prevent Rust from accessing useful C++ functionality.

            
            //

            
            // Declarations using this annotation must be registered in the

            
            // `do_not_bind_allowlist` or bindings generation will fail with a hard error.

            
            #define CRUBIT_DO_NOT_BIND CRUBIT_INTERNAL_ANNOTATE("crubit_do_not_bind")


            // Marks a function or method as having `pub(crate)` visibility in the generated

            
            // Rust bindings, restricting its visibility to the crate being generated.

            
            //

            
            // This is useful when providing custom handwritten Rust wrappers or extensions

            
            // via the `srcs` attribute of `rust_api_from_cpp`. Annotated C++ functions or

            
            // methods will be accessible to those custom Rust sources within the same

            
            // crate, but will not be exposed to downstream Rust callers.

            
            //

            
            // This annotation can only be applied to functions and methods. Using it on

            
            // types will result in a compilation error.

            
            #define CRUBIT_PUB_CRATE CRUBIT_INTERNAL_ANNOTATE("crubit_pub_crate")


            // By default, crubit.rs will infer Rust safety based on the types of the

            
            // function's parameters. This annotation can be used to override that

            
            // inference.

            
            #define CRUBIT_OVERRIDE_UNSAFE(function_is_unsafe) \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_override_unsafe", function_is_unsafe)


            // This annotation configures a user-defined rust name for a C++ declaration.

            
            // If the user-defined rust name conflicts with an existing name, bindings for

            
            // both the annotated decl and the conflicting decl will fail, and be treated as

            
            // overloads.

            
            //

            
            // For example, this C++ header:

            
            //

            
            // ```c++

            
            // CRUBIT_RUST_NAME("foo")

            
            // int bar() { return 42; }

            
            // ```

            
            //

            
            // Becomes this Rust interface:

            
            //

            
            // ```rust

            
            // pub fn foo() -> i32;  // returns 42

            
            // ```

            
            //

            
            // There's a special case for operators: when an operator symbol is given, for

            
            // example `CRUBIT_RUST_NAME("!")`, the function is mapped to the corresponding

            
            // Rust operator trait, in this case `core::ops::Not`.

            
            //

            
            // ```c++

            
            // CRUBIT_RUST_NAME("!")

            
            // MyInt operator~(MyInt x);

            
            // ```

            
            //

            
            // ```rust

            
            // impl core::ops::Not for MyInt {

            
            //   type Output = Self;

            
            //

            
            //   fn not(self) -> Self::Output { /* calls operator~ */ }

            
            // }

            
            // ```

            
            #define CRUBIT_RUST_NAME(crubit_rust_name) \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_rust_name", crubit_rust_name)


            // This annotation is used to mark a function as `unsafe` to Rust callers.

            
            //

            
            // For example, this C++ header:

            
            //

            
            // ```c++

            
            // CRUBIT_UNSAFE

            
            // int foo() { return 42; }

            
            // ```

            
            //

            
            // Becomes this Rust interface:

            
            //

            
            // ```rust

            
            // pub unsafe fn foo() -> i32;  // returns 42

            
            // ```

            
            //

            
            // By default, crubit.rs will infer Rust safety based on the types of the

            
            // function's parameters. This annotation can be used to override that

            
            // inference.

            
            #define CRUBIT_UNSAFE CRUBIT_OVERRIDE_UNSAFE(true)


            // This annotation is used to mark a function as `safe` to Rust callers

            
            // regardless of the types of the function's parameters.

            
            //

            
            // For example, this C++ header:

            
            //

            
            // ```c++

            
            // CRUBIT_UNSAFE_MARK_SAFE

            
            // uint64_t foo(uint64_t* unsafe_ptr) { return 42; }

            
            // ```

            
            //

            
            // Becomes this Rust interface:

            
            //

            
            // ```rust

            
            // pub fn foo(*mut u64) -> u64;  // returns 42

            
            // ```

            
            //

            
            // By default, crubit.rs will infer Rust safety based on the types of the

            
            // function's parameters. This annotation can be used to override that

            
            // inference.

            
            #define CRUBIT_UNSAFE_MARK_SAFE CRUBIT_OVERRIDE_UNSAFE(false)


            // Overrides the `Debug` binding generation for a struct, class, or union.

            
            //

            
            // By default, Crubit generates a custom `Debug` implementation for all concrete

            
            // structs/classes and all unions, but not abstract structs/classes. Use

            
            // `CRUBIT_OVERRIDE_DEBUG` to opt-out (or opt-in for abstract types).

            
            //

            
            // Unlike Rust's `derive(Debug)`, does not require all fields to `impl Debug`.

            
            // However, only guaranteed to be exhaustive if all the following hold:

            
            // * The type is a struct or class, not a union.

            
            // * Every field is supported, named, and implements `Debug`, including

            
            //   non-generic Rust types that implement `Debug`.

            
            // * The type has no bases.

            
            #define CRUBIT_OVERRIDE_DEBUG(should_bind) \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_override_debug", should_bind)


            // Marks a type as deriving a trait.

            
            //

            
            // This can be applied to a struct, class, or enum.

            
            //

            
            // For example, this C++ header:

            
            //

            
            // ```c++

            
            // struct CRUBIT_TRAIT_DERIVE("Clone") MyStruct {

            
            //     bool enable_foo;

            
            // };

            
            // ```

            
            //

            
            // Becomes this Rust interface:

            
            //

            
            // ```rust

            
            // #[derive(..., Clone)]

            
            // pub struct MyStruct {

            
            //   enable_foo: bool,

            
            // }

            
            // ```

            
            //

            
            // TODO(b/475834520): Deriving `Debug` will be deprecated in favor of the

            
            // default behavior. To opt out of the default `Debug` implementation, use

            
            // `CRUBIT_OVERRIDE_DEBUG(false)`.

            
            //

            
            // `"!Send"` and `"!Sync"` can be used to opt a type out of `Send` / `Sync`,

            
            // producing `impl !Send for MyStruct {}` / `impl !Sync for MyStruct {}`. This

            
            // is already the default, unless the `infer_send_sync` Crubit feature is

            
            // enabled (see `CRUBIT_UNSAFE_IMPL`). Positive `Send` / `Sync` must use

            
            // `CRUBIT_UNSAFE_IMPL` instead.

            
            #define CRUBIT_TRAIT_DERIVE(...)                                         \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_internal_trait_derive" __VA_OPT__(, ) \

            
                                           __VA_ARGS__)


            // Marks a type as unsafely implementing one or more marker traits.

            
            //

            
            // This can be applied to a struct, class, or enum.

            
            //

            
            // For example, this C++ header:

            
            //

            
            // ```c++

            
            // struct

            
            //   CRUBIT_UNSAFE_IMPL("Send", "Sync") MyStruct {

            
            //     bool enable_foo;

            
            // };

            
            // ```

            
            //

            
            // Becomes this Rust interface:

            
            //

            
            // ```rust

            
            // pub struct MyStruct {

            
            //   enable_foo: bool,

            
            // }

            
            //

            
            // unsafe impl Send for MyStruct {}

            
            // unsafe impl Sync for MyStruct {}

            
            // ```

            
            //

            
            // By default, types without this annotation get `impl !Send` and `impl !Sync`.

            
            // With the `infer_send_sync` Crubit feature, they instead get no impl at all,

            
            // and Rust infers `Send` and `Sync` from the fields, just as it does for Rust

            
            // types. Fields that Crubit represents as opaque bytes (e.g. non-public fields,

            
            // fields of unsupported types, and base class subobjects) are treated as

            
            // neither `Send` nor `Sync`. Use `CRUBIT_TRAIT_DERIVE("!Send")` /

            
            // `CRUBIT_TRAIT_DERIVE("!Sync")` to opt out of inference for a type which must

            
            // not be sent or shared between threads, e.g. because it is thread-affine.

            
            #define CRUBIT_UNSAFE_IMPL(...)                                         \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_internal_unsafe_impl" __VA_OPT__(, ) \

            
                                           __VA_ARGS__)


            // Marks a type as bridging to a Rust type.

            
            //

            
            // # Warning

            
            //

            
            // Composable bridging on user-defined types is still highly experimental.

            
            //

            
            // # Usage

            
            //

            
            // * rust_name: The name of the Rust type.

            
            // * abi_rust: The Crubit ABI of the Rust type.

            
            // * abi_cpp: The Crubit ABI of the C++ type.

            
            // * label_hint: (Optional) The target that owns the Rust type.

            
            //   Format: "//package:target" or a short-form like

            
            //   "@abseil-cpp//absl/status".

            
            //

            
            // From absl::StatusOr:

            
            //

            
            // ```c++

            
            // #include "absl/status/status.h"  # from

            
            // @abseil-cpp//absl/status:status

            
            //

            
            // template <typename T>

            
            // class

            
            // CRUBIT_BRIDGE("::status::absl::StatusOr", "::status::absl::StatusOrAbi",

            
            //               "::crubit::StatusOrAbi", "@abseil-cpp//absl/status:status")

            
            //               StatusOr;

            
            // ```

            
            #define CRUBIT_BRIDGE_3(rust_name, abi_rust, abi_cpp)            \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_rust_name", rust_name) \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_abi_rust", abi_rust)   \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_abi_cpp", abi_cpp)


            #define CRUBIT_BRIDGE_4(rust_name, abi_rust, abi_cpp, label_hint) \

            
              CRUBIT_BRIDGE_3(rust_name, abi_rust, abi_cpp)                   \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_label_hint", label_hint)


            #define CRUBIT_BRIDGE_GET_MACRO(_1, _2, _3, _4, NAME, ...) NAME

            
            #define CRUBIT_BRIDGE(...)                              \

            
              CRUBIT_BRIDGE_GET_MACRO(__VA_ARGS__, CRUBIT_BRIDGE_4, \

            
                                      CRUBIT_BRIDGE_3)(__VA_ARGS__)


            // Prevents Crubit from interpreting one or more named attributes on this

            
            // declaration.

            
            //

            
            // ```c++

            
            // // example.h

            
            // // SAFETY: `my_attribute` does not affect ABI.

            
            // struct CRUBIT_UNSAFE_IGNORE_ATTR("my_attr") [[my_attr]] MyStruct {};

            
            // ```

            
            #define CRUBIT_UNSAFE_IGNORE_ATTR(...)                                \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_unsafe_ignore_attr" __VA_OPT__(, ) \

            
                                           __VA_ARGS__)


            // The CRUBIT_OWNED_POINTER AND CRUBIT_OWNED_POINTEE annotations work together

            
            // to map conventionally "owned" C++ pointer usages to a Rust type that provides

            
            // Rust-style ownership wrapping a raw pointer.

            
            //

            
            // Think carefully before using these annotations. These annotations exist to

            
            // support existing APIs that use raw pointers directly, and can not be

            
            // modified; if your API can be improved to avoid dealing with raw pointers (for

            
            // example, by using the managed C++ pointer types that crubit supports) that's

            
            // almost certainly the preferable solution.

            
            //

            
            // Types annotated with `CRUBIT_OWNED_PTR` indicate a transfer of ownership: for

            
            // example, in the return position, they indicate that the function is passing

            
            // ownership of the pointed-to object to the caller. Similarly, in a parameter

            
            // position, the callee receiving ownership of the pointed-to object.

            
            //

            
            // The annotation is only meaningful on pointer types. When a pointer is

            
            // annotated with `CRUBIT_OWNED_PTR`, the pointee type must also be annotated

            
            // with `CRUBIT_OWNED_PTR_TYPE`, indicating the Rust type that will manage the

            
            // ownership of the object in Rust bindings.

            
            //

            
            // The annotation pair is meant to associate Rust types that simply contain a

            
            // pointer to the associated C++ type.

            
            //

            
            // For example:

            
            //

            
            // ```c++

            
            // struct CRUBIT_OWNED_POINTEE("WrapperTypeName") MyType;

            
            //

            
            // MyType* CRUBIT_OWNED_POINTER ReturnOwnedPtr() { ... }

            
            // void AcceptOwnedPtr(MyType* CRUBIT_OWNED_POINTER owned_ptr) { ... }

            
            // ```

            
            //

            
            // This will generate a Rust struct called `WrapperTypeName` that simply

            
            // contains a pointer to the underlying object. This type will be used in

            
            // positions that are annotated with `CRUBIT_OWNED_POINTER`.

            
            //

            
            // You can optionally specify a custom drop method name as a second argument:

            
            // `CRUBIT_OWNED_POINTEE("WrapperTypeName", "DropMethodName")`. If omitted, it

            
            // defaults to `DropImpl`.


            #define CRUBIT_OWNED_POINTER \

            
              CRUBIT_INTERNAL_ANNOTATE_TYPE("crubit_owned_pointer")

            
            #define CRUBIT_OWNED_POINTEE(name, ...)            \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_owned_pointee", \

            
                                       name __VA_OPT__(, ) __VA_ARGS__)


            // Overrides the `Display` binding detection for a type to true or false.

            
            //

            
            // If detected: binds to Rust's `Display` trait, preferring `AbslStringify` over

            
            // `std::ostream&` `operator<<` but requiring either.

            
            //

            
            // By default, infers a type `T`'s formatability based on one of:

            
            // * `template <typename Sink> void AbslStringify(Sink&, const T&)`

            
            // * `template <typename Sink> void AbslStringify(Sink&, T)`

            
            // * `std::ostream& operator<<(std::ostream&, const T&)`

            
            // * `std::ostream& operator<<(std::ostream&, T)`

            
            // * This annotation on `T`'s bases

            
            //

            
            // in any of the following:

            
            // * `T`'s namespace

            
            // * `T`'s friends

            
            // * `T`'s bases' namespace and friends

            
            //

            
            // and recurses on the bases of `T`. e.g., if `T` inherits from `B`, then

            
            // looks for both `AbslStringify(Sink&, T)` and `AbslStringify(Sink&, B)` in

            
            // `B`.

            
            //

            
            // However, default inference does *not* handle all cases, including:

            
            // * Other function or function template signatures e.g.,

            
            //   ```c++

            
            //   template <typename Sink, typename T>

            
            //   void AbslStringify(Sink&, const Foo<T>&);

            
            //

            
            //   template <typename T>

            
            //   struct Bar {

            
            //     template <

            
            //         typename U = T,

            
            //         typename = std::enable_if_t<absl::HasOstreamOperator<U>::value>>

            
            //     friend std::ostream& operator<<(std::ostream&, const Bar&);

            
            //   };

            
            //

            
            //   template <typename T>

            
            //   struct Baz {

            
            //     friend std::ostream& operator<<(std::ostream&, const Bar&)

            
            //     requires(absl::HasOstreamOperator<T>::value);

            
            //   };

            
            //

            
            //   struct Qux {

            
            //     template <typename T, typename Traits>

            
            //     friend std::basic_ostream<T, Traits>& operator<<(

            
            //         std::basic_ostream<T, Traits>&, const Qux&);

            
            //   };

            
            //   ```

            
            // * Formattable but non-public bases

            
            // * Deleted functions

            
            #define CRUBIT_OVERRIDE_DISPLAY(should_bind) \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_override_display", should_bind)


            // Marks a type as thread-safe for Rust interop.

            
            //

            
            // This is an unsafe operation. Only use this annotation on thread-safe types

            
            // which are never created as `const`, or else which mark all fields that can

            
            // be mutated as `mutable`, even if those fields can only be mutated from a

            
            // non-const method.

            
            //

            
            // Types annotated with `CRUBIT_THREAD_SAFE` will:

            
            //

            
            // * Implement `Send + Sync` in Rust

            
            // * Have their internal representation wrapped in `UnsafeCell`, allowing

            
            //   non-const C++ methods to be called via shared references (`&self`)

            
            //

            
            // This annotation is appropriate for types that internally synchronize

            
            // access (e.g., types with mutexes, atomics, or other synchronization

            
            // primitives). However, it places strong requirements on the type's C++ users

            
            // and/or the C++ type owner: either the type must never be created as a top

            
            // level `const` object, or else all mutating operations must be made valid on a

            
            // `const` object, by marking all mutated fields as `mutable`.

            
            //

            
            // Example:

            
            //

            
            // ```c++

            
            // class CRUBIT_THREAD_SAFE ThreadSafeCounter {

            
            //   public:

            
            //     void Increment();      // Can be called via mut T*.

            
            //     int Get() const;       // Can also be called via &self

            
            //   private:

            
            //     mutable std::atomic<int> count_;

            
            // };

            
            // ```

            
            //

            
            // See crubit.rs/cpp/cookbook#thread_safety

            
            //

            
            #define CRUBIT_THREAD_SAFE CRUBIT_INTERNAL_ANNOTATE("crubit_thread_safe")


            // Marks a template or template instance as always instantiated.

            
            //

            
            // Example:

            
            // ```c++

            
            //   using MyInst CRUBIT_ALWAYS_INSTANTIATE = MyTemplate<int>;

            
            // ```

            
            #define CRUBIT_ALWAYS_INSTANTIATE \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_always_instantiate")


            // Creates a uniquely-named using declaration that aliases `tp`, annotated with

            
            // `CRUBIT_ALWAYS_INSTANTIATE`.

            
            //

            
            // Example:

            
            // ```c++

            
            //   CRUBIT_BIND_INSTANTIATION(MyTemplate<int>);

            
            // ```

            
            #define CRUBIT_BIND_INSTANTIATION(tp...)                                       \

            
              namespace {                                                                  \

            
              using CRUBIT_INTERNAL_EXPAND_AND_CONCAT(                                     \

            
                  crubit_bind_instantiation_, __COUNTER__) CRUBIT_ALWAYS_INSTANTIATE = tp; \

            
              }


            // Suppresses the warning on types defined in the `srcs` of a

            
            // `rust_api_from_cpp` target that will not receive C++ bindings.

            
            #define CRUBIT_ALLOW_UNBINDABLE_TYPE \

            
              CRUBIT_INTERNAL_ANNOTATE("crubit_allow_unbindable_type")


            #endif  // THIRD_PARTY_CRUBIT_SUPPORT_ANNOTATIONS_H_
	// Part of the Crubit project, under the Apache License v2.0 with LLVM
	// Exceptions. See /LICENSE for license information.
	// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

	// IWYU pragma: private, include "support/annotations.h"

	#ifndef THIRD_PARTY_CRUBIT_SUPPORT_ANNOTATIONS_H_
	#define THIRD_PARTY_CRUBIT_SUPPORT_ANNOTATIONS_H_

	#include "support/annotations_internal.h"

	// SWIG does not follow `#include` directives, so it cannot see the definitions
	// below and reports "Syntax error in input" when it parses a header that uses
	// these annotations. To make SWIG treat them as no-ops, add
	// `%include "support/annotations.swig"` to the `.swig` file
	// (after `%include "base/swig/google.swig"`), and add
	// `//support:annotations_swig` to the SWIG rule's
	// `swig_includes`. See b/566029265.

	// Marks a function or type as requiring Rust binding.
	//
	// If Crubit fails to generate bindings for a function or type annotated with
	// `CRUBIT_MUST_BIND`, bindings generation for the entire target will fail
	// with a hard error.
	//
	// This can be useful when developing C++ API surfaces that are intended to be
	// used from Rust, as it produces a clear error message when a function is
	// missing bindings.
	//
	// For example, this C++ header will silently not produce bindings for
	// `foo` because overloads are not supported.
	//
	// ```c++
	// void foo();
	// void foo(int x);
	// void bar();
	// ```
	//
	// This default behavior allows `bar` to still receive bindings.
	//
	// By contrast, this C++ header will fail at binding generation time with an
	// error message describing that overloads are not supported:
	//
	// ```c++
	// CRUBIT_MUST_BIND void foo();
	// void foo(int x);
	// void bar();
	// ```
	//
	// The annotation can also be applied to a type:
	//
	// ```c++
	// struct CRUBIT_MUST_BIND Foo {
	// int x;
	// };
	// ```
	#define CRUBIT_MUST_BIND CRUBIT_INTERNAL_ANNOTATE("crubit_must_bind")

	// Prevents a function or type from receiving Rust bindings.
	//
	// Use of this annotation should be avoided where-possible as usage of it can
	// prevent Rust from accessing useful C++ functionality.
	//
	// Declarations using this annotation must be registered in the
	// `do_not_bind_allowlist` or bindings generation will fail with a hard error.
	#define CRUBIT_DO_NOT_BIND CRUBIT_INTERNAL_ANNOTATE("crubit_do_not_bind")

	// Marks a function or method as having `pub(crate)` visibility in the generated
	// Rust bindings, restricting its visibility to the crate being generated.
	//
	// This is useful when providing custom handwritten Rust wrappers or extensions
	// via the `srcs` attribute of `rust_api_from_cpp`. Annotated C++ functions or
	// methods will be accessible to those custom Rust sources within the same
	// crate, but will not be exposed to downstream Rust callers.
	//
	// This annotation can only be applied to functions and methods. Using it on
	// types will result in a compilation error.
	#define CRUBIT_PUB_CRATE CRUBIT_INTERNAL_ANNOTATE("crubit_pub_crate")

	// By default, crubit.rs will infer Rust safety based on the types of the
	// function's parameters. This annotation can be used to override that
	// inference.
	#define CRUBIT_OVERRIDE_UNSAFE(function_is_unsafe) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_override_unsafe", function_is_unsafe)

	// This annotation configures a user-defined rust name for a C++ declaration.
	// If the user-defined rust name conflicts with an existing name, bindings for
	// both the annotated decl and the conflicting decl will fail, and be treated as
	// overloads.
	//
	// For example, this C++ header:
	//
	// ```c++
	// CRUBIT_RUST_NAME("foo")
	// int bar() { return 42; }
	// ```
	//
	// Becomes this Rust interface:
	//
	// ```rust
	// pub fn foo() -> i32; // returns 42
	// ```
	//
	// There's a special case for operators: when an operator symbol is given, for
	// example `CRUBIT_RUST_NAME("!")`, the function is mapped to the corresponding
	// Rust operator trait, in this case `core::ops::Not`.
	//
	// ```c++
	// CRUBIT_RUST_NAME("!")
	// MyInt operator~(MyInt x);
	// ```
	//
	// ```rust
	// impl core::ops::Not for MyInt {
	// type Output = Self;
	//
	// fn not(self) -> Self::Output { /* calls operator~ */ }
	// }
	// ```
	#define CRUBIT_RUST_NAME(crubit_rust_name) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_rust_name", crubit_rust_name)

	// This annotation is used to mark a function as `unsafe` to Rust callers.
	//
	// For example, this C++ header:
	//
	// ```c++
	// CRUBIT_UNSAFE
	// int foo() { return 42; }
	// ```
	//
	// Becomes this Rust interface:
	//
	// ```rust
	// pub unsafe fn foo() -> i32; // returns 42
	// ```
	//
	// By default, crubit.rs will infer Rust safety based on the types of the
	// function's parameters. This annotation can be used to override that
	// inference.
	#define CRUBIT_UNSAFE CRUBIT_OVERRIDE_UNSAFE(true)

	// This annotation is used to mark a function as `safe` to Rust callers
	// regardless of the types of the function's parameters.
	//
	// For example, this C++ header:
	//
	// ```c++
	// CRUBIT_UNSAFE_MARK_SAFE
	// uint64_t foo(uint64_t* unsafe_ptr) { return 42; }
	// ```
	//
	// Becomes this Rust interface:
	//
	// ```rust
	// pub fn foo(*mut u64) -> u64; // returns 42
	// ```
	//
	// By default, crubit.rs will infer Rust safety based on the types of the
	// function's parameters. This annotation can be used to override that
	// inference.
	#define CRUBIT_UNSAFE_MARK_SAFE CRUBIT_OVERRIDE_UNSAFE(false)

	// Overrides the `Debug` binding generation for a struct, class, or union.
	//
	// By default, Crubit generates a custom `Debug` implementation for all concrete
	// structs/classes and all unions, but not abstract structs/classes. Use
	// `CRUBIT_OVERRIDE_DEBUG` to opt-out (or opt-in for abstract types).
	//
	// Unlike Rust's `derive(Debug)`, does not require all fields to `impl Debug`.
	// However, only guaranteed to be exhaustive if all the following hold:
	// * The type is a struct or class, not a union.
	// * Every field is supported, named, and implements `Debug`, including
	// non-generic Rust types that implement `Debug`.
	// * The type has no bases.
	#define CRUBIT_OVERRIDE_DEBUG(should_bind) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_override_debug", should_bind)

	// Marks a type as deriving a trait.
	//
	// This can be applied to a struct, class, or enum.
	//
	// For example, this C++ header:
	//
	// ```c++
	// struct CRUBIT_TRAIT_DERIVE("Clone") MyStruct {
	// bool enable_foo;
	// };
	// ```
	//
	// Becomes this Rust interface:
	//
	// ```rust
	// #[derive(..., Clone)]
	// pub struct MyStruct {
	// enable_foo: bool,
	// }
	// ```
	//
	// TODO(b/475834520): Deriving `Debug` will be deprecated in favor of the
	// default behavior. To opt out of the default `Debug` implementation, use
	// `CRUBIT_OVERRIDE_DEBUG(false)`.
	//
	// `"!Send"` and `"!Sync"` can be used to opt a type out of `Send` / `Sync`,
	// producing `impl !Send for MyStruct {}` / `impl !Sync for MyStruct {}`. This
	// is already the default, unless the `infer_send_sync` Crubit feature is
	// enabled (see `CRUBIT_UNSAFE_IMPL`). Positive `Send` / `Sync` must use
	// `CRUBIT_UNSAFE_IMPL` instead.
	#define CRUBIT_TRAIT_DERIVE(...) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_internal_trait_derive" __VA_OPT__(, ) \
	__VA_ARGS__)

	// Marks a type as unsafely implementing one or more marker traits.
	//
	// This can be applied to a struct, class, or enum.
	//
	// For example, this C++ header:
	//
	// ```c++
	// struct
	// CRUBIT_UNSAFE_IMPL("Send", "Sync") MyStruct {
	// bool enable_foo;
	// };
	// ```
	//
	// Becomes this Rust interface:
	//
	// ```rust
	// pub struct MyStruct {
	// enable_foo: bool,
	// }
	//
	// unsafe impl Send for MyStruct {}
	// unsafe impl Sync for MyStruct {}
	// ```
	//
	// By default, types without this annotation get `impl !Send` and `impl !Sync`.
	// With the `infer_send_sync` Crubit feature, they instead get no impl at all,
	// and Rust infers `Send` and `Sync` from the fields, just as it does for Rust
	// types. Fields that Crubit represents as opaque bytes (e.g. non-public fields,
	// fields of unsupported types, and base class subobjects) are treated as
	// neither `Send` nor `Sync`. Use `CRUBIT_TRAIT_DERIVE("!Send")` /
	// `CRUBIT_TRAIT_DERIVE("!Sync")` to opt out of inference for a type which must
	// not be sent or shared between threads, e.g. because it is thread-affine.
	#define CRUBIT_UNSAFE_IMPL(...) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_internal_unsafe_impl" __VA_OPT__(, ) \
	__VA_ARGS__)

	// Marks a type as bridging to a Rust type.
	//
	// # Warning
	//
	// Composable bridging on user-defined types is still highly experimental.
	//
	// # Usage
	//
	// * rust_name: The name of the Rust type.
	// * abi_rust: The Crubit ABI of the Rust type.
	// * abi_cpp: The Crubit ABI of the C++ type.
	// * label_hint: (Optional) The target that owns the Rust type.
	// Format: "//package:target" or a short-form like
	// "@abseil-cpp//absl/status".
	//
	// From absl::StatusOr:
	//
	// ```c++
	// #include "absl/status/status.h" # from
	// @abseil-cpp//absl/status:status
	//
	// template <typename T>
	// class
	// CRUBIT_BRIDGE("::status::absl::StatusOr", "::status::absl::StatusOrAbi",
	// "::crubit::StatusOrAbi", "@abseil-cpp//absl/status:status")
	// StatusOr;
	// ```
	#define CRUBIT_BRIDGE_3(rust_name, abi_rust, abi_cpp) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_rust_name", rust_name) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_abi_rust", abi_rust) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_abi_cpp", abi_cpp)

	#define CRUBIT_BRIDGE_4(rust_name, abi_rust, abi_cpp, label_hint) \
	CRUBIT_BRIDGE_3(rust_name, abi_rust, abi_cpp) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_bridge_label_hint", label_hint)

	#define CRUBIT_BRIDGE_GET_MACRO(_1, _2, _3, _4, NAME, ...) NAME
	#define CRUBIT_BRIDGE(...) \
	CRUBIT_BRIDGE_GET_MACRO(__VA_ARGS__, CRUBIT_BRIDGE_4, \
	CRUBIT_BRIDGE_3)(__VA_ARGS__)

	// Prevents Crubit from interpreting one or more named attributes on this
	// declaration.
	//
	// ```c++
	// // example.h
	// // SAFETY: `my_attribute` does not affect ABI.
	// struct CRUBIT_UNSAFE_IGNORE_ATTR("my_attr") [[my_attr]] MyStruct {};
	// ```
	#define CRUBIT_UNSAFE_IGNORE_ATTR(...) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_unsafe_ignore_attr" __VA_OPT__(, ) \
	__VA_ARGS__)

	// The CRUBIT_OWNED_POINTER AND CRUBIT_OWNED_POINTEE annotations work together
	// to map conventionally "owned" C++ pointer usages to a Rust type that provides
	// Rust-style ownership wrapping a raw pointer.
	//
	// Think carefully before using these annotations. These annotations exist to
	// support existing APIs that use raw pointers directly, and can not be
	// modified; if your API can be improved to avoid dealing with raw pointers (for
	// example, by using the managed C++ pointer types that crubit supports) that's
	// almost certainly the preferable solution.
	//
	// Types annotated with `CRUBIT_OWNED_PTR` indicate a transfer of ownership: for
	// example, in the return position, they indicate that the function is passing
	// ownership of the pointed-to object to the caller. Similarly, in a parameter
	// position, the callee receiving ownership of the pointed-to object.
	//
	// The annotation is only meaningful on pointer types. When a pointer is
	// annotated with `CRUBIT_OWNED_PTR`, the pointee type must also be annotated
	// with `CRUBIT_OWNED_PTR_TYPE`, indicating the Rust type that will manage the
	// ownership of the object in Rust bindings.
	//
	// The annotation pair is meant to associate Rust types that simply contain a
	// pointer to the associated C++ type.
	//
	// For example:
	//
	// ```c++
	// struct CRUBIT_OWNED_POINTEE("WrapperTypeName") MyType;
	//
	// MyType* CRUBIT_OWNED_POINTER ReturnOwnedPtr() { ... }
	// void AcceptOwnedPtr(MyType* CRUBIT_OWNED_POINTER owned_ptr) { ... }
	// ```
	//
	// This will generate a Rust struct called `WrapperTypeName` that simply
	// contains a pointer to the underlying object. This type will be used in
	// positions that are annotated with `CRUBIT_OWNED_POINTER`.
	//
	// You can optionally specify a custom drop method name as a second argument:
	// `CRUBIT_OWNED_POINTEE("WrapperTypeName", "DropMethodName")`. If omitted, it
	// defaults to `DropImpl`.

	#define CRUBIT_OWNED_POINTER \
	CRUBIT_INTERNAL_ANNOTATE_TYPE("crubit_owned_pointer")
	#define CRUBIT_OWNED_POINTEE(name, ...) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_owned_pointee", \
	name __VA_OPT__(, ) __VA_ARGS__)

	// Overrides the `Display` binding detection for a type to true or false.
	//
	// If detected: binds to Rust's `Display` trait, preferring `AbslStringify` over
	// `std::ostream&` `operator<<` but requiring either.
	//
	// By default, infers a type `T`'s formatability based on one of:
	// * `template <typename Sink> void AbslStringify(Sink&, const T&)`
	// * `template <typename Sink> void AbslStringify(Sink&, T)`
	// * `std::ostream& operator<<(std::ostream&, const T&)`
	// * `std::ostream& operator<<(std::ostream&, T)`
	// * This annotation on `T`'s bases
	//
	// in any of the following:
	// * `T`'s namespace
	// * `T`'s friends
	// * `T`'s bases' namespace and friends
	//
	// and recurses on the bases of `T`. e.g., if `T` inherits from `B`, then
	// looks for both `AbslStringify(Sink&, T)` and `AbslStringify(Sink&, B)` in
	// `B`.
	//
	// However, default inference does not handle all cases, including:
	// * Other function or function template signatures e.g.,
	// ```c++
	// template <typename Sink, typename T>
	// void AbslStringify(Sink&, const Foo<T>&);
	//
	// template <typename T>
	// struct Bar {
	// template <
	// typename U = T,
	// typename = std::enable_if_t<absl::HasOstreamOperator<U>::value>>
	// friend std::ostream& operator<<(std::ostream&, const Bar&);
	// };
	//
	// template <typename T>
	// struct Baz {
	// friend std::ostream& operator<<(std::ostream&, const Bar&)
	// requires(absl::HasOstreamOperator<T>::value);
	// };
	//
	// struct Qux {
	// template <typename T, typename Traits>
	// friend std::basic_ostream<T, Traits>& operator<<(
	// std::basic_ostream<T, Traits>&, const Qux&);
	// };
	// ```
	// * Formattable but non-public bases
	// * Deleted functions
	#define CRUBIT_OVERRIDE_DISPLAY(should_bind) \
	CRUBIT_INTERNAL_ANNOTATE("crubit_override_display", should_bind)

	// Marks a type as thread-safe for Rust interop.
	//
	// This is an unsafe operation. Only use this annotation on thread-safe types
	// which are never created as `const`, or else which mark all fields that can
	// be mutated as `mutable`, even if those fields can only be mutated from a
	// non-const method.
	//
	// Types annotated with `CRUBIT_THREAD_SAFE` will:
	//
	// * Implement `Send + Sync` in Rust
	// * Have their internal representation wrapped in `UnsafeCell`, allowing
	// non-const C++ methods to be called via shared references (`&self`)
	//
	// This annotation is appropriate for types that internally synchronize
	// access (e.g., types with mutexes, atomics, or other synchronization
	// primitives). However, it places strong requirements on the type's C++ users
	// and/or the C++ type owner: either the type must never be created as a top
	// level `const` object, or else all mutating operations must be made valid on a
	// `const` object, by marking all mutated fields as `mutable`.
	//
	// Example:
	//
	// ```c++
	// class CRUBIT_THREAD_SAFE ThreadSafeCounter {
	// public:
	// void Increment(); // Can be called via mut T*.
	// int Get() const; // Can also be called via &self
	// private:
	// mutable std::atomic<int> count_;
	// };
	// ```
	//
	// See crubit.rs/cpp/cookbook#thread_safety
	//
	#define CRUBIT_THREAD_SAFE CRUBIT_INTERNAL_ANNOTATE("crubit_thread_safe")

	// Marks a template or template instance as always instantiated.
	//
	// Example:
	// ```c++
	// using MyInst CRUBIT_ALWAYS_INSTANTIATE = MyTemplate<int>;
	// ```
	#define CRUBIT_ALWAYS_INSTANTIATE \
	CRUBIT_INTERNAL_ANNOTATE("crubit_always_instantiate")

	// Creates a uniquely-named using declaration that aliases `tp`, annotated with
	// `CRUBIT_ALWAYS_INSTANTIATE`.
	//
	// Example:
	// ```c++
	// CRUBIT_BIND_INSTANTIATION(MyTemplate<int>);
	// ```
	#define CRUBIT_BIND_INSTANTIATION(tp...) \
	namespace { \
	using CRUBIT_INTERNAL_EXPAND_AND_CONCAT( \
	crubit_bind_instantiation_, __COUNTER__) CRUBIT_ALWAYS_INSTANTIATE = tp; \
	}

	// Suppresses the warning on types defined in the `srcs` of a
	// `rust_api_from_cpp` target that will not receive C++ bindings.
	#define CRUBIT_ALLOW_UNBINDABLE_TYPE \
	CRUBIT_INTERNAL_ANNOTATE("crubit_allow_unbindable_type")

	#endif // THIRD_PARTY_CRUBIT_SUPPORT_ANNOTATIONS_H_