diff --git a/libraries/common/src/main/java/androidx/media3/common/C.java b/libraries/common/src/main/java/androidx/media3/common/C.java index fd42dca63a..440292516d 100644 --- a/libraries/common/src/main/java/androidx/media3/common/C.java +++ b/libraries/common/src/main/java/androidx/media3/common/C.java @@ -1235,17 +1235,33 @@ public final class C { @UnstableApi public static final int PROJECTION_MESH = 3; /** - * Priority for media playback. + * A value indicating the priority of a operation. * *

Larger values indicate higher priorities. + * + *

The predefined priority values are used by default and it's recommended to align any custom + * values relative to these defaults (for example, {@code C.PRIORITY_PLAYBACK - 1}. + * + *

Predefined values are (in descending priority order): + * + *

*/ + @Documented + @UnstableApi + @Retention(RetentionPolicy.SOURCE) + @Target(TYPE_USE) + @IntDef( + open = true, + value = {PRIORITY_PLAYBACK, PRIORITY_DOWNLOAD}) + public @interface Priority {} + + /** {@link Priority} for active media playback. */ @UnstableApi public static final int PRIORITY_PLAYBACK = 0; - /** - * Priority for media downloading. - * - *

Larger values indicate higher priorities. - */ + /** {@link Priority} for media downloading unrelated to active playback. */ @UnstableApi public static final int PRIORITY_DOWNLOAD = PRIORITY_PLAYBACK - 1000; /** diff --git a/libraries/common/src/main/java/androidx/media3/common/PriorityTaskManager.java b/libraries/common/src/main/java/androidx/media3/common/PriorityTaskManager.java index 309a5efc45..3c8a57e9e7 100644 --- a/libraries/common/src/main/java/androidx/media3/common/PriorityTaskManager.java +++ b/libraries/common/src/main/java/androidx/media3/common/PriorityTaskManager.java @@ -24,12 +24,16 @@ import java.util.Collections; import java.util.PriorityQueue; /** - * Allows tasks with associated priorities to control how they proceed relative to one another. + * Allows tasks with associated {@linkplain C.Priority priorities} to control how they proceed + * relative to one another. * *

A task should call {@link #add(int)} to register with the manager and {@link #remove(int)} to * unregister. A registered task will prevent tasks of lower priority from proceeding, and should * call {@link #proceed(int)}, {@link #proceedNonBlocking(int)} or {@link #proceedOrThrow(int)} each * time it wishes to check whether it is itself allowed to proceed. + * + *

It is recommended to use predefined {@linkplain C.Priority priorities} or priority values + * defined relative to those defaults. */ @UnstableApi public final class PriorityTaskManager { @@ -37,7 +41,7 @@ public final class PriorityTaskManager { /** Thrown when task attempts to proceed when another registered task has a higher priority. */ public static class PriorityTooLowException extends IOException { - public PriorityTooLowException(int priority, int highestPriority) { + public PriorityTooLowException(@C.Priority int priority, @C.Priority int highestPriority) { super("Priority too low [priority=" + priority + ", highest=" + highestPriority + "]"); } } @@ -45,8 +49,8 @@ public final class PriorityTaskManager { private final Object lock = new Object(); // Guarded by lock. - private final PriorityQueue queue; - private int highestPriority; + private final PriorityQueue<@C.Priority Integer> queue; + private @C.Priority int highestPriority; public PriorityTaskManager() { queue = new PriorityQueue<>(10, Collections.reverseOrder()); @@ -56,9 +60,12 @@ public final class PriorityTaskManager { /** * Register a new task. The task must call {@link #remove(int)} when done. * - * @param priority The priority of the task. Larger values indicate higher priorities. + *

It is recommended to use predefined {@linkplain C.Priority priorities} or priority values + * defined relative to those defaults. + * + * @param priority The {@link C.Priority} of the task. Larger values indicate higher priorities. */ - public void add(int priority) { + public void add(@C.Priority int priority) { synchronized (lock) { queue.add(priority); highestPriority = max(highestPriority, priority); @@ -68,10 +75,10 @@ public final class PriorityTaskManager { /** * Blocks until the task is allowed to proceed. * - * @param priority The priority of the task. + * @param priority The {@link C.Priority} of the task. * @throws InterruptedException If the thread is interrupted. */ - public void proceed(int priority) throws InterruptedException { + public void proceed(@C.Priority int priority) throws InterruptedException { synchronized (lock) { while (highestPriority != priority) { lock.wait(); @@ -82,10 +89,10 @@ public final class PriorityTaskManager { /** * A non-blocking variant of {@link #proceed(int)}. * - * @param priority The priority of the task. + * @param priority The {@link C.Priority} of the task. * @return Whether the task is allowed to proceed. */ - public boolean proceedNonBlocking(int priority) { + public boolean proceedNonBlocking(@C.Priority int priority) { synchronized (lock) { return highestPriority == priority; } @@ -94,10 +101,10 @@ public final class PriorityTaskManager { /** * A throwing variant of {@link #proceed(int)}. * - * @param priority The priority of the task. + * @param priority The {@link C.Priority} of the task. * @throws PriorityTooLowException If the task is not allowed to proceed. */ - public void proceedOrThrow(int priority) throws PriorityTooLowException { + public void proceedOrThrow(@C.Priority int priority) throws PriorityTooLowException { synchronized (lock) { if (highestPriority != priority) { throw new PriorityTooLowException(priority, highestPriority); @@ -108,9 +115,9 @@ public final class PriorityTaskManager { /** * Unregister a task. * - * @param priority The priority of the task. + * @param priority The {@link C.Priority} of the task. */ - public void remove(int priority) { + public void remove(@C.Priority int priority) { synchronized (lock) { queue.remove(priority); highestPriority = queue.isEmpty() ? Integer.MIN_VALUE : Util.castNonNull(queue.peek()); diff --git a/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSource.java b/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSource.java index ee7c1e065c..f00a8d37fc 100644 --- a/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSource.java +++ b/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSource.java @@ -17,6 +17,7 @@ package androidx.media3.datasource; import android.net.Uri; import androidx.annotation.Nullable; +import androidx.media3.common.C; import androidx.media3.common.PriorityTaskManager; import androidx.media3.common.util.Assertions; import androidx.media3.common.util.UnstableApi; @@ -45,7 +46,7 @@ public final class PriorityDataSource implements DataSource { private final DataSource.Factory upstreamFactory; private final PriorityTaskManager priorityTaskManager; - private final int priority; + private final @C.Priority int priority; /** * Creates an instance. @@ -54,11 +55,13 @@ public final class PriorityDataSource implements DataSource { * DataSources} for {@link PriorityDataSource} instances created by the factory. * @param priorityTaskManager The {@link PriorityTaskManager} to which tasks using {@link * PriorityDataSource} instances created by this factory will be registered. - * @param priority The priority of the tasks using {@link PriorityDataSource} instances created - * by this factory. + * @param priority The {@link C.Priority} of the tasks using {@link PriorityDataSource} + * instances created by this factory. */ public Factory( - DataSource.Factory upstreamFactory, PriorityTaskManager priorityTaskManager, int priority) { + DataSource.Factory upstreamFactory, + PriorityTaskManager priorityTaskManager, + @C.Priority int priority) { this.upstreamFactory = upstreamFactory; this.priorityTaskManager = priorityTaskManager; this.priority = priority; @@ -73,15 +76,15 @@ public final class PriorityDataSource implements DataSource { private final DataSource upstream; private final PriorityTaskManager priorityTaskManager; - private final int priority; + private final @C.Priority int priority; /** * @param upstream The upstream {@link DataSource}. * @param priorityTaskManager The priority manager to which the task is registered. - * @param priority The priority of the task. + * @param priority The {@link C.Priority} of the task. */ public PriorityDataSource( - DataSource upstream, PriorityTaskManager priorityTaskManager, int priority) { + DataSource upstream, PriorityTaskManager priorityTaskManager, @C.Priority int priority) { this.upstream = Assertions.checkNotNull(upstream); this.priorityTaskManager = Assertions.checkNotNull(priorityTaskManager); this.priority = priority; diff --git a/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSourceFactory.java b/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSourceFactory.java index cf86a22164..d5dd4b7012 100644 --- a/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSourceFactory.java +++ b/libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSourceFactory.java @@ -15,6 +15,7 @@ */ package androidx.media3.datasource; +import androidx.media3.common.C; import androidx.media3.common.PriorityTaskManager; import androidx.media3.common.util.UnstableApi; import androidx.media3.datasource.DataSource.Factory; @@ -28,16 +29,16 @@ public final class PriorityDataSourceFactory implements Factory { private final Factory upstreamFactory; private final PriorityTaskManager priorityTaskManager; - private final int priority; + private final @C.Priority int priority; /** * @param upstreamFactory A {@link DataSource.Factory} to be used to create an upstream {@link * DataSource} for {@link PriorityDataSource}. * @param priorityTaskManager The priority manager to which PriorityDataSource task is registered. - * @param priority The priority of PriorityDataSource task. + * @param priority The {@link C.Priority} of the {@link PriorityDataSource} task. */ public PriorityDataSourceFactory( - Factory upstreamFactory, PriorityTaskManager priorityTaskManager, int priority) { + Factory upstreamFactory, PriorityTaskManager priorityTaskManager, @C.Priority int priority) { this.upstreamFactory = upstreamFactory; this.priorityTaskManager = priorityTaskManager; this.priority = priority; diff --git a/libraries/datasource/src/main/java/androidx/media3/datasource/cache/CacheDataSource.java b/libraries/datasource/src/main/java/androidx/media3/datasource/cache/CacheDataSource.java index e4c665229f..2dca5a4382 100644 --- a/libraries/datasource/src/main/java/androidx/media3/datasource/cache/CacheDataSource.java +++ b/libraries/datasource/src/main/java/androidx/media3/datasource/cache/CacheDataSource.java @@ -72,7 +72,7 @@ public final class CacheDataSource implements DataSource { private boolean cacheIsReadOnly; @Nullable private DataSource.Factory upstreamDataSourceFactory; @Nullable private PriorityTaskManager upstreamPriorityTaskManager; - private int upstreamPriority; + private @C.Priority int upstreamPriority; private @CacheDataSource.Flags int flags; @Nullable private CacheDataSource.EventListener eventListener; @@ -209,16 +209,17 @@ public final class CacheDataSource implements DataSource { } /** - * Sets the priority to use when requesting data from upstream. The priority is only used if a - * {@link PriorityTaskManager} is set by calling {@link #setUpstreamPriorityTaskManager}. + * Sets the {@link C.Priority} to use when requesting data from upstream. The priority is only + * used if a {@link PriorityTaskManager} is set by calling {@link + * #setUpstreamPriorityTaskManager}. * *

The default is {@link C#PRIORITY_PLAYBACK}. * - * @param upstreamPriority The priority to use when requesting data from upstream. + * @param upstreamPriority The {@link C.Priority} to use when requesting data from upstream. * @return This factory. */ @CanIgnoreReturnValue - public Factory setUpstreamPriority(int upstreamPriority) { + public Factory setUpstreamPriority(@C.Priority int upstreamPriority) { this.upstreamPriority = upstreamPriority; return this; } @@ -297,7 +298,9 @@ public final class CacheDataSource implements DataSource { } private CacheDataSource createDataSourceInternal( - @Nullable DataSource upstreamDataSource, @Flags int flags, int upstreamPriority) { + @Nullable DataSource upstreamDataSource, + @Flags int flags, + @C.Priority int upstreamPriority) { Cache cache = checkNotNull(this.cache); @Nullable DataSink cacheWriteDataSink; if (cacheIsReadOnly || upstreamDataSource == null) { @@ -531,7 +534,7 @@ public final class CacheDataSource implements DataSource { @Nullable CacheKeyFactory cacheKeyFactory, @Flags int flags, @Nullable PriorityTaskManager upstreamPriorityTaskManager, - int upstreamPriority, + @C.Priority int upstreamPriority, @Nullable EventListener eventListener) { this.cache = cache; this.cacheReadDataSource = cacheReadDataSource;