Merge "Introduce intial EconomyManagerInternal interface."

apex/jobscheduler/service/java/com/android/server/tare/EconomyManagerInternal.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright (C) 2021 The Android Open Source Project
+ *
+ * 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.android.server.tare;
+
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+
+/**
+ * Interface for the system server to deal with the resource economy subsystem.
+ *
+ * @hide
+ */
+interface EconomyManagerInternal {
+    /** Listener for when an app changes its solvency status. */
+    interface BalanceChangeListener {
+        /**
+         * Called when an app runs out of funds.
+         * {@link #noteOngoingEventStopped(int, String, String, String)} must still be called to formally
+         * end the action.
+         */
+        void onBankruptcy(int userId, @NonNull String pkgName);
+
+        /**
+         * Called when an app goes from being insolvent to solvent.
+         */
+        void onSolvent(int userId, @NonNull String pkgName);
+    }
+
+    /** Register a {@link BalanceChangeListener} to track all apps' solvency status changes. */
+    void registerBalanceChangeListener(@NonNull BalanceChangeListener listener);
+
+    /**
+     * Unregister a {@link BalanceChangeListener} from being notified of any app's solvency status
+     * changes.
+     */
+    void unregisterBalanceChangeListener(@NonNull BalanceChangeListener listener);
+
+    /**
+     * Return {@code true} if the app has a balance equal to or greater than the specified min
+     * balance.
+     */
+    boolean hasBalanceAtLeast(int userId, @NonNull String pkgName, double minBalance);
+
+    /**
+     * Note that an instantaneous event has occurred. The event must be specified in one of the
+     * EconomicPolicies.
+     *
+     * @param tag An optional tag that can be used to differentiate the same event for the same app.
+     */
+    void noteInstantaneousEvent(int userId, @NonNull String pkgName, @NonNull String event,
+            @Nullable String tag);
+
+    /**
+     * Note that a long-running event is starting. The event must be specified in one of the
+     * EconomicPolicies. You must always call
+     * {@link #noteOngoingEventStopped(int, String, String, String)} to end the event. Ongoing
+     * events will be separated and grouped by event-tag combinations. There must be an equal
+     * number of start() and stop() calls for the same event-tag combination in order for the
+     * tracking to finally stop (ie. ongoing events are ref-counted).
+     *
+     * @param tag An optional tag that can be used to differentiate the same event for the same app.
+     */
+    void noteOngoingEventStarted(int userId, @NonNull String pkgName, @NonNull String event,
+            @Nullable String tag);
+
+    /**
+     * Note that a long-running event has stopped. The event must be specified in one of the
+     * EconomicPolicies. Ongoing events are separated and grouped by event-tag combinations.
+     * There must be an equal number of start() and stop() calls for the same event-tag combination
+     * in order for the tracking to finally stop (ie. ongoing events are ref-counted).
+     *
+     * @param tag An optional tag that can be used to differentiate the same event for the same app.
+     */
+    void noteOngoingEventStopped(int userId, @NonNull String pkgName, @NonNull String event,
+            @Nullable String tag);
+}