Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0034ddd4 authored by Sanath Kumar's avatar Sanath Kumar
Browse files

Add new stop reason for maybe abandoned jobs 

Jobs timed out and detected as "Maybe Abandoned" jobs will be reported
as a new stop reason.

bug: 372529068
Test: Existing CTS and unit tests pass
Flag: android.app.job.handle_abandoned_jobs
Change-Id: Ia2bf137748ccb43ea980ba7298be339612f419b5
parent 5e272ac5

apex/jobscheduler/framework/java/android/app/job/JobParameters.java

+38 −0
Original line number Original line Diff line number Diff line
@@ -16,6 +16,7 @@ 




package android.app.job;

package android.app.job;





import android.annotation.FlaggedApi;

import android.annotation.IntDef;

import android.annotation.IntDef;

import android.annotation.NonNull;

import android.annotation.NonNull;

import android.annotation.Nullable;

import android.annotation.Nullable;
@@ -120,6 +121,15 @@ public class JobParameters implements Parcelable { 
    public static final int INTERNAL_STOP_REASON_ANR =

    public static final int INTERNAL_STOP_REASON_ANR =

            JobProtoEnums.INTERNAL_STOP_REASON_ANR; // 12.

            JobProtoEnums.INTERNAL_STOP_REASON_ANR; // 12.





    /**

     * The job ran for at least its minimum execution limit and the app lost the strong reference

     * to the {@link JobParameters}. This could indicate that the job is empty because the app

     * can no longer call {@link JobService#jobFinished(JobParameters, boolean)}.

     * @hide

     */

    public static final int INTERNAL_STOP_REASON_TIMEOUT_ABANDONED =

            JobProtoEnums.INTERNAL_STOP_REASON_TIMEOUT_ABANDONED; // 13.



    /**

    /**

     * All the stop reason codes. This should be regarded as an immutable array at runtime.

     * All the stop reason codes. This should be regarded as an immutable array at runtime.

     *

     *
@@ -144,6 +154,7 @@ public class JobParameters implements Parcelable { 
            INTERNAL_STOP_REASON_SUCCESSFUL_FINISH,

            INTERNAL_STOP_REASON_SUCCESSFUL_FINISH,

            INTERNAL_STOP_REASON_USER_UI_STOP,

            INTERNAL_STOP_REASON_USER_UI_STOP,

            INTERNAL_STOP_REASON_ANR,

            INTERNAL_STOP_REASON_ANR,

            INTERNAL_STOP_REASON_TIMEOUT_ABANDONED,

    };

    };





    /**

    /**
@@ -166,6 +177,7 @@ public class JobParameters implements Parcelable { 
            case INTERNAL_STOP_REASON_SUCCESSFUL_FINISH: return "successful_finish";

            case INTERNAL_STOP_REASON_SUCCESSFUL_FINISH: return "successful_finish";

            case INTERNAL_STOP_REASON_USER_UI_STOP: return "user_ui_stop";

            case INTERNAL_STOP_REASON_USER_UI_STOP: return "user_ui_stop";

            case INTERNAL_STOP_REASON_ANR: return "anr";

            case INTERNAL_STOP_REASON_ANR: return "anr";

            case INTERNAL_STOP_REASON_TIMEOUT_ABANDONED: return "timeout_abandoned";

            default: return "unknown:" + reasonCode;

            default: return "unknown:" + reasonCode;

        }

        }

    }

    }
@@ -269,6 +281,25 @@ public class JobParameters implements Parcelable { 
     */

     */

    public static final int STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED = 15;

    public static final int STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED = 15;





    /**

     * The job used up its maximum execution time and timed out. The system also detected that the

     * app can no longer call {@link JobService#jobFinished(JobParameters, boolean)} for this job,

     * likely because the strong reference to the job handle ({@link JobParameters}) passed to it

     * via {@link JobService#onStartJob(JobParameters)} was lost. This can occur even if the app

     * called {@link JobScheduler#cancel(int)}, {@link JobScheduler#cancelAll()}, or

     * {@link JobScheduler#cancelInAllNamespaces()} to stop an active job while losing strong

     * references to the job handle. In this case, the job is not necessarily abandoned. However,

     * the system cannot distinguish such cases from truly abandoned jobs.

     * <p>

     * It is recommended that you use {@link JobService#jobFinished(JobParameters, boolean)} or

     * return false from {@link JobService#onStartJob(JobParameters)} to stop an active job. This

     * will prevent the occurrence of this stop reason and the need to handle it. The primary use

     * case for this stop reason is to report a probable case of a job being abandoned.

     * <p>

     */

    @FlaggedApi(Flags.FLAG_HANDLE_ABANDONED_JOBS)

    public static final int STOP_REASON_TIMEOUT_ABANDONED = 16;



    /** @hide */

    /** @hide */

    @IntDef(prefix = {"STOP_REASON_"}, value = {

    @IntDef(prefix = {"STOP_REASON_"}, value = {

            STOP_REASON_UNDEFINED,

            STOP_REASON_UNDEFINED,
@@ -287,6 +318,7 @@ public class JobParameters implements Parcelable { 
            STOP_REASON_USER,

            STOP_REASON_USER,

            STOP_REASON_SYSTEM_PROCESSING,

            STOP_REASON_SYSTEM_PROCESSING,

            STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED,

            STOP_REASON_ESTIMATED_APP_LAUNCH_TIME_CHANGED,

            STOP_REASON_TIMEOUT_ABANDONED,

    })

    })

    @Retention(RetentionPolicy.SOURCE)

    @Retention(RetentionPolicy.SOURCE)

    public @interface StopReason {

    public @interface StopReason {
@@ -361,6 +393,12 @@ public class JobParameters implements Parcelable { 
    }

    }





    /**

    /**

     * Returns the reason {@link JobService#onStopJob(JobParameters)} was called on this job.

     * <p>

     * Apps should not rely on the stop reason for critical decision-making, as additional stop

     * reasons may be added in subsequent Android releases. The primary intended use of this method

     * is for logging and diagnostic purposes to gain insights into the causes of job termination.

     * <p>

     * @return The reason {@link JobService#onStopJob(JobParameters)} was called on this job. Will

     * @return The reason {@link JobService#onStopJob(JobParameters)} was called on this job. Will

     * be {@link #STOP_REASON_UNDEFINED} if {@link JobService#onStopJob(JobParameters)} has not

     * be {@link #STOP_REASON_UNDEFINED} if {@link JobService#onStopJob(JobParameters)} has not

     * yet been called.

     * yet been called.

core/api/current.txt

+1 −0
Original line number Original line Diff line number Diff line
@@ -9218,6 +9218,7 @@ package android.app.job { 
    field public static final int STOP_REASON_QUOTA = 10; // 0xa

    field public static final int STOP_REASON_QUOTA = 10; // 0xa

    field public static final int STOP_REASON_SYSTEM_PROCESSING = 14; // 0xe

    field public static final int STOP_REASON_SYSTEM_PROCESSING = 14; // 0xe

    field public static final int STOP_REASON_TIMEOUT = 3; // 0x3

    field public static final int STOP_REASON_TIMEOUT = 3; // 0x3

    field @FlaggedApi("android.app.job.handle_abandoned_jobs") public static final int STOP_REASON_TIMEOUT_ABANDONED = 16; // 0x10

    field public static final int STOP_REASON_UNDEFINED = 0; // 0x0

    field public static final int STOP_REASON_UNDEFINED = 0; // 0x0

    field public static final int STOP_REASON_USER = 13; // 0xd

    field public static final int STOP_REASON_USER = 13; // 0xd

  }

  }