Add PerformanceSensitive annotations (#2037)

Document module, class, and/or method performance considerations.

changelog/@unreleased/pr-2037.v2.yml

@@ -0,0 +1,5 @@
+type: improvement
+improvement:
+  description: Document module, class, and/or method performance characteristics.
+  links:
+  - https://github.com/palantir/tritium/pull/2037

tritium-annotations/build.gradle

@@ -11,4 +11,8 @@ dependencies {
     implementation 'com.google.code.findbugs:jsr305'
     implementation 'com.palantir.safe-logging:preconditions'
     implementation 'org.slf4j:slf4j-api'
+
+    testImplementation 'org.assertj:assertj-core'
+    testImplementation 'org.junit.jupiter:junit-jupiter'
+    testImplementation 'org.junit.jupiter:junit-jupiter-api'
 }

tritium-annotations/src/main/java/com/palantir/tritium/annotations/PerformanceSensitive.java

@@ -0,0 +1,59 @@
+/*
+ * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.tritium.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Elements annotated with {@link PerformanceSensitive} indicate that there are performance considerations to balance
+ * when modifying this element.
+ */
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.MODULE})
+@Retention(RetentionPolicy.SOURCE)
+public @interface PerformanceSensitive {
+
+    /**
+     * The reasons this element is considered performance sensitive.
+     */
+    Consideration[] value();
+
+    enum Consideration {
+
+        /**
+         * This element is sensitive to object allocations.
+         */
+        ALLOCATION,
+
+        /**
+         * This element is sensitive to cache access patterns.
+         */
+        CACHE,
+
+        /**
+         * This element is sensitive to overall latency.
+         */
+        LATENCY,
+
+        /**
+         * This element is sensitive to overall throughput.
+         */
+        THROUGHPUT,
+    }
+}

tritium-annotations/src/test/java/com/palantir/tritium/annotations/PerformanceSensitiveTest.java

@@ -0,0 +1,46 @@
+/*
+ * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.tritium.annotations;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.palantir.tritium.annotations.PerformanceSensitive.Consideration;
+import org.junit.jupiter.api.Test;
+
+public class PerformanceSensitiveTest {
+
+    @Test
+    void annotationValues() {
+        assertThat(expensive()).isEqualTo(999_000_000);
+    }
+
+    @PerformanceSensitive({
+        Consideration.ALLOCATION,
+        Consideration.CACHE,
+        Consideration.LATENCY,
+        Consideration.THROUGHPUT,
+    })
+    static long expensive() {
+        long sum = 0;
+        for (int i = 0; i < 1_000; i++) {
+            for (int j = 0; j < 1_000; j++) {
+                sum += i + j;
+            }
+        }
+        return sum;
+    }
+}