Add @ForegroundSafe / @BackgroundOnly marker annotations (#12471)

Add @ForegroundSafe / @BackgroundOnly marker annotations

Documentation-and-tooling markers declaring whether code is cheap
enough for application (foreground) threads or must be confined to a
background thread the tracer paces itself. No application to real
code yet and no checker -- just the annotation types, following the
Strategy/StrategyConsumer marker convention (APMLP-1543).

Merge branch 'master' into dougqh/foreground-safe-background-only-annotations

Co-authored-by: devflow.devflow-routing-intake <devflow.devflow-routing-intake@kubernetes.us1.ddbuild.io>

Author: dougqh

internal-api/src/main/java/datadog/trace/api/function/BackgroundOnly.java

@@ -0,0 +1,33 @@
+package datadog.trace.api.function;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks code that must be confined to a background thread the tracer owns and paces itself -- e.g.
+ * serialization, stats aggregation, or eviction -- and must never be reached from an application
+ * thread (the foreground; see {@link ForegroundSafe}), where its cost would become customer-visible
+ * latency instead.
+ *
+ * <p>This is a documentation-and-tooling marker; it changes no behavior. It exists to telegraph the
+ * constraint to readers and to give a future checker (see {@code APMLP-1645}) something to verify
+ * -- that no {@code @BackgroundOnly} code is reachable from a foreground call site. The discipline
+ * it names is <b>not yet enforced</b>; hold to it by hand until the checker lands.
+ *
+ * <p>The two markers are <b>not symmetric</b> -- see {@link ForegroundSafe} for why it, not this
+ * one, is the strictly stronger guarantee.
+ *
+ * <p><b>On a type</b> ({@link ElementType#TYPE}): every method of this type is background-only
+ * unless a method-level {@link ForegroundSafe} widens it.
+ *
+ * <p><b>On a method</b> ({@link ElementType#METHOD}): this method specifically is background-only,
+ * regardless of what the enclosing type declares -- a method-level marker always wins over the
+ * type-level one.
+ */
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.TYPE, ElementType.METHOD})
+public @interface BackgroundOnly {}

internal-api/src/main/java/datadog/trace/api/function/ForegroundSafe.java

@@ -0,0 +1,36 @@
+package datadog.trace.api.function;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks code cheap enough to call from an application thread (the foreground) -- the request or
+ * transaction thread the instrumented application itself is running, where any added cost is
+ * customer-visible latency, as opposed to a background thread the tracer owns and paces itself (see
+ * {@link BackgroundOnly}).
+ *
+ * <p>This is a documentation-and-tooling marker; it changes no behavior. It exists to telegraph the
+ * guarantee to readers and to give a future checker (see {@code APMLP-1645}) something to verify --
+ * that no {@link BackgroundOnly} code is reachable from a foreground call site. The discipline it
+ * names is <b>not yet enforced</b>; hold to it by hand until the checker lands.
+ *
+ * <p>The two markers are <b>not symmetric</b>. {@code @ForegroundSafe} is the strictly stronger
+ * guarantee: code cheap enough for the foreground is automatically fine to call from a background
+ * thread too, so a {@code @ForegroundSafe} type or method may be called from either. {@link
+ * BackgroundOnly} code carries no such guarantee and must never be reached from a foreground call
+ * site.
+ *
+ * <p><b>On a type</b> ({@link ElementType#TYPE}): every method of this type is foreground-safe
+ * unless a method-level {@link BackgroundOnly} narrows it.
+ *
+ * <p><b>On a method</b> ({@link ElementType#METHOD}): this method specifically is foreground-safe,
+ * regardless of what the enclosing type declares -- a method-level marker always wins over the
+ * type-level one.
+ */
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.TYPE, ElementType.METHOD})
+public @interface ForegroundSafe {}