loliball/media3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add IntDef for priority values

Browse Source 
This makes it easier to reference these values in documentation
and method parameters.

PiperOrigin-RevId: 629072314
This commit is contained in:
tonihei 2024-04-29 08:11:34 -07:00 committed by Copybara-Service
parent e180e263a5
commit 344fc8a8c0
5 changed files with 67 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
libraries/common/src/main/java/androidx/media3/common/C.java
View File

@ -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.
*
* <p>Larger values indicate higher priorities.
*
* <p>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}.
*
* <p>Predefined values are (in descending priority order):
*
* <ul>
* <li>{@link #PRIORITY_PLAYBACK}
* <li>{@link #PRIORITY_DOWNLOAD}
* </ul>
*/
@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.
*
* <p>Larger values indicate higher priorities.
*/
/** {@link Priority} for media downloading unrelated to active playback. */
@UnstableApi public static final int PRIORITY_DOWNLOAD = PRIORITY_PLAYBACK - 1000;
/**

35
libraries/common/src/main/java/androidx/media3/common/PriorityTaskManager.java
View File

@ -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.
*
* <p>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.
*
* <p>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<Integer> 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.
* <p>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());

17
libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSource.java
View File

@ -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;

7
libraries/datasource/src/main/java/androidx/media3/datasource/PriorityDataSourceFactory.java
View File

@ -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;

17
libraries/datasource/src/main/java/androidx/media3/datasource/cache/CacheDataSource.java vendored
View File

@ -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}.
*
* <p>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;