diff options
Diffstat (limited to 'spark-api/src')
8 files changed, 531 insertions, 0 deletions
diff --git a/spark-api/src/main/java/me/lucko/spark/api/Spark.java b/spark-api/src/main/java/me/lucko/spark/api/Spark.java new file mode 100644 index 0000000..1f4ee64 --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/Spark.java @@ -0,0 +1,79 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api; + +import me.lucko.spark.api.gc.GarbageCollector; +import me.lucko.spark.api.statistic.misc.DoubleAverageInfo; +import me.lucko.spark.api.statistic.types.DoubleStatistic; +import me.lucko.spark.api.statistic.types.GenericStatistic; +import me.lucko.spark.api.statistic.StatisticWindow; + +import org.checkerframework.checker.nullness.qual.NonNull; +import org.checkerframework.checker.nullness.qual.Nullable; +import org.jetbrains.annotations.Unmodifiable; + +import java.util.Map; + +/** + * The spark API. + */ +public interface Spark { + + /** + * Gets the CPU usage statistic for the current process. + * + * @return the CPU process statistic + */ + @NonNull DoubleStatistic<StatisticWindow.CpuUsage> cpuProcess(); + + /** + * Gets the CPU usage statistic for the overall system. + * + * @return the CPU system statistic + */ + @NonNull DoubleStatistic<StatisticWindow.CpuUsage> cpuSystem(); + + /** + * Gets the ticks per second statistic. + * + * <p>Returns {@code null} if the statistic is not supported.</p> + * + * @return the ticks per second statistic + */ + @Nullable DoubleStatistic<StatisticWindow.TicksPerSecond> tps(); + + /** + * Gets the milliseconds per tick statistic. + * + * <p>Returns {@code null} if the statistic is not supported.</p> + * + * @return the milliseconds per tick statistic + */ + @Nullable GenericStatistic<DoubleAverageInfo, StatisticWindow.MillisPerTick> mspt(); + + /** + * Gets the garbage collector statistics. + * + * @return the garbage collector statistics + */ + @NonNull @Unmodifiable Map<String, GarbageCollector> gc(); + +} diff --git a/spark-api/src/main/java/me/lucko/spark/api/SparkProvider.java b/spark-api/src/main/java/me/lucko/spark/api/SparkProvider.java new file mode 100644 index 0000000..a93c27d --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/SparkProvider.java @@ -0,0 +1,53 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api; + +import org.checkerframework.checker.nullness.qual.NonNull; + +/** + * Singleton provider for {@link Spark}. + */ +public final class SparkProvider { + + private static Spark instance; + + /** + * Gets the singleton spark API instance. + * + * @return the spark API instance + */ + public static @NonNull Spark get() { + Spark instance = SparkProvider.instance; + if (instance == null) { + throw new IllegalStateException("spark has not loaded yet!"); + } + return instance; + } + + static void set(Spark impl) { + SparkProvider.instance = impl; + } + + private SparkProvider() { + throw new AssertionError(); + } + +} diff --git a/spark-api/src/main/java/me/lucko/spark/api/gc/GarbageCollector.java b/spark-api/src/main/java/me/lucko/spark/api/gc/GarbageCollector.java new file mode 100644 index 0000000..b2c8801 --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/gc/GarbageCollector.java @@ -0,0 +1,73 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api.gc; + +import org.checkerframework.checker.nullness.qual.NonNull; + +/** + * Statistics about a garbage collector. + * + * <p>All time durations are measured in milliseconds.</p> + */ +public interface GarbageCollector { + + /** + * Gets the name of the garbage collector. + * + * @return the name + */ + @NonNull String name(); + + /** + * Gets the total number of collections performed. + * + * @return the total number of collections + */ + long totalCollections(); + + /** + * Gets the total amount of time spent performing collections. + * + * <p>Measured in milliseconds.</p> + * + * @return the total time spent collecting + */ + long totalTime(); + + /** + * Gets the average amount of time spent performing each collection. + * + * <p>Measured in milliseconds.</p> + * + * @return the average collection time + */ + double avgTime(); + + /** + * Gets the average frequency at which collections are performed. + * + * <p>Measured in milliseconds.</p> + * + * @return the average frequency of collections + */ + long avgFrequency(); + +} diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/Statistic.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/Statistic.java new file mode 100644 index 0000000..26af8e1 --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/Statistic.java @@ -0,0 +1,46 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api.statistic; + +import org.checkerframework.checker.nullness.qual.NonNull; + +/** + * A statistic for which a rolling average in various windows is recorded. + * + * @param <W> the window type + */ +public interface Statistic<W extends Enum<W> & StatisticWindow> { + + /** + * Gets the statistic name. + * + * @return the statistic name + */ + @NonNull String name(); + + /** + * Gets the windows used for rolling averages. + * + * @return the windows + */ + @NonNull W[] getWindows(); + +} diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/StatisticWindow.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/StatisticWindow.java new file mode 100644 index 0000000..cfae9dd --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/StatisticWindow.java @@ -0,0 +1,104 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api.statistic; + +import org.checkerframework.checker.nullness.qual.NonNull; +import org.jetbrains.annotations.NotNull; + +import java.time.Duration; + +/** + * A window in which a statistic is recorded as a rolling average. + */ +public interface StatisticWindow { + + /** + * Gets the length of the window as a {@link Duration}. + * + * @return the length of the window + */ + @NonNull Duration length(); + + /** + * The {@link StatisticWindow} used for CPU usage. + */ + enum CpuUsage implements StatisticWindow { + + SECONDS_10(Duration.ofSeconds(10)), + MINUTES_1(Duration.ofMinutes(1)), + MINUTES_15(Duration.ofMinutes(15)); + + private final Duration value; + + CpuUsage(Duration value) { + this.value = value; + } + + @Override + public @NotNull Duration length() { + return this.value; + } + } + + /** + * The {@link StatisticWindow} used for TPS. + */ + enum TicksPerSecond implements StatisticWindow { + + SECONDS_5(Duration.ofSeconds(5)), + SECONDS_10(Duration.ofSeconds(10)), + MINUTES_1(Duration.ofMinutes(1)), + MINUTES_5(Duration.ofMinutes(5)), + MINUTES_15(Duration.ofMinutes(15)); + + private final Duration value; + + TicksPerSecond(Duration value) { + this.value = value; + } + + @Override + public @NotNull Duration length() { + return this.value; + } + } + + /** + * The {@link StatisticWindow} used for MSPT. + */ + enum MillisPerTick implements StatisticWindow { + + SECONDS_10(Duration.ofSeconds(10)), + MINUTES_1(Duration.ofMinutes(1)); + + private final Duration value; + + MillisPerTick(Duration value) { + this.value = value; + } + + @Override + public @NotNull Duration length() { + return this.value; + } + } + +} diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/misc/DoubleAverageInfo.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/misc/DoubleAverageInfo.java new file mode 100644 index 0000000..0f882de --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/misc/DoubleAverageInfo.java @@ -0,0 +1,75 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api.statistic.misc; + +/** + * Statistics for a recorded double value. + */ +public interface DoubleAverageInfo { + + /** + * Gets the mean value. + * + * @return the mean + */ + double mean(); + + /** + * Gets the max value. + * + * @return the max + */ + double max(); + + /** + * Gets the min value. + * + * @return the min + */ + double min(); + + /** + * Gets the median value. + * + * @return the median + */ + default double median() { + return percentile(0.50d); + } + + /** + * Gets the 95th percentile value. + * + * @return the 95th percentile + */ + default double percentile95th() { + return percentile(0.95d); + } + + /** + * Gets the average value at a given percentile. + * + * @param percentile the percentile, as a double between 0 and 1. + * @return the average value at the given percentile + */ + double percentile(double percentile); + +} diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/types/DoubleStatistic.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/DoubleStatistic.java new file mode 100644 index 0000000..ab26b7b --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/DoubleStatistic.java @@ -0,0 +1,50 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api.statistic.types; + +import me.lucko.spark.api.statistic.Statistic; +import me.lucko.spark.api.statistic.StatisticWindow; + +import org.checkerframework.checker.nullness.qual.NonNull; + +/** + * A {@link Statistic} with a {@code double} value. + * + * @param <W> the window type + */ +public interface DoubleStatistic<W extends Enum<W> & StatisticWindow> extends Statistic<W> { + + /** + * Polls the current value of the statistic in the given window. + * + * @param window the window + * @return the value + */ + double poll(@NonNull W window); + + /** + * Polls the current values of the statistic in all windows. + * + * @return the values + */ + double[] poll(); + +} diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/types/GenericStatistic.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/GenericStatistic.java new file mode 100644 index 0000000..2c27c05 --- /dev/null +++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/GenericStatistic.java @@ -0,0 +1,51 @@ +/* + * This file is part of spark. + * + * Copyright (c) lucko (Luck) <luck@lucko.me> + * Copyright (c) contributors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +package me.lucko.spark.api.statistic.types; + +import me.lucko.spark.api.statistic.Statistic; +import me.lucko.spark.api.statistic.StatisticWindow; + +import org.checkerframework.checker.nullness.qual.NonNull; + +/** + * A {@link Statistic} with a generic (non-primitive) type. + * + * @param <T> the generic value type + * @param <W> the window type + */ +public interface GenericStatistic<T, W extends Enum<W> & StatisticWindow> extends Statistic<W> { + + /** + * Polls the current value of the statistic in the given window. + * + * @param window the window + * @return the value + */ + T poll(@NonNull W window); + + /** + * Polls the current values of the statistic in all windows. + * + * @return the values + */ + T[] poll(); + +} |