From 61c93e224a862a078cbcb2ea1415e93a20307532 Mon Sep 17 00:00:00 2001
From: David Schlosnagle <davids@palantir.com>
Date: Thu, 3 Oct 2024 09:11:30 -0400
Subject: [PATCH] Add PerformanceSensitive annotations (#2037)

Document module, class, and/or method performance considerations.
---
 changelog/@unreleased/pr-2037.v2.yml          |  5 ++
 tritium-annotations/build.gradle              |  4 ++
 .../annotations/PerformanceSensitive.java     | 59 +++++++++++++++++++
 .../annotations/PerformanceSensitiveTest.java | 46 +++++++++++++++
 4 files changed, 114 insertions(+)
 create mode 100644 changelog/@unreleased/pr-2037.v2.yml
 create mode 100644 tritium-annotations/src/main/java/com/palantir/tritium/annotations/PerformanceSensitive.java
 create mode 100644 tritium-annotations/src/test/java/com/palantir/tritium/annotations/PerformanceSensitiveTest.java

diff --git a/changelog/@unreleased/pr-2037.v2.yml b/changelog/@unreleased/pr-2037.v2.yml
new file mode 100644
index 000000000..e8b576c73
--- /dev/null
+++ b/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
diff --git a/tritium-annotations/build.gradle b/tritium-annotations/build.gradle
index c20aeff58..fcb56c76c 100644
--- a/tritium-annotations/build.gradle
+++ b/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'
 }
diff --git a/tritium-annotations/src/main/java/com/palantir/tritium/annotations/PerformanceSensitive.java b/tritium-annotations/src/main/java/com/palantir/tritium/annotations/PerformanceSensitive.java
new file mode 100644
index 000000000..9e0dd9b9a
--- /dev/null
+++ b/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,
+    }
+}
diff --git a/tritium-annotations/src/test/java/com/palantir/tritium/annotations/PerformanceSensitiveTest.java b/tritium-annotations/src/test/java/com/palantir/tritium/annotations/PerformanceSensitiveTest.java
new file mode 100644
index 000000000..356314443
--- /dev/null
+++ b/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;
+    }
+}