Implement support for request priorities

Author: lucasr

picasso/src/main/java/com/squareup/picasso/Action.java

@@ -17,6 +17,7 @@
 
 import android.graphics.Bitmap;
 import android.graphics.drawable.Drawable;
+import com.squareup.picasso.Picasso.Priority;
 import java.lang.ref.ReferenceQueue;
 import java.lang.ref.WeakReference;
 
@@ -85,4 +86,8 @@ boolean willReplay() {
   Picasso getPicasso() {
     return picasso;
   }
+
+  Priority getPriority() {
+    return request.priority;
+  }
 }

picasso/src/main/java/com/squareup/picasso/BitmapHunter.java

@@ -24,8 +24,11 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.Future;
+import java.util.concurrent.atomic.AtomicInteger;
 
 import static com.squareup.picasso.Picasso.LoadedFrom.MEMORY;
+import static com.squareup.picasso.Picasso.Priority;
+import static com.squareup.picasso.Picasso.Priority.LOW;
 import static com.squareup.picasso.Utils.OWNER_HUNTER;
 import static com.squareup.picasso.Utils.VERB_DECODED;
 import static com.squareup.picasso.Utils.VERB_EXECUTING;
@@ -49,6 +52,9 @@ class BitmapHunter implements Runnable {
     }
   };
 
+  private static final AtomicInteger SEQUENCE_GENERATOR = new AtomicInteger();
+
+  final int sequence;
   final Picasso picasso;
   final Dispatcher dispatcher;
   final Cache cache;
@@ -66,9 +72,11 @@ class BitmapHunter implements Runnable {
   Exception exception;
   int exifRotation; // Determined during decoding of original resource.
   int retryCount;
+  Priority priority;
 
   BitmapHunter(Picasso picasso, Dispatcher dispatcher, Cache cache, Stats stats, Action action,
                RequestHandler requestHandler) {
+    this.sequence = SEQUENCE_GENERATOR.incrementAndGet();
     this.picasso = picasso;
     this.dispatcher = dispatcher;
     this.cache = cache;
@@ -79,6 +87,7 @@ class BitmapHunter implements Runnable {
     this.requestHandler = requestHandler;
     this.retryCount = requestHandler.getRetryCount();
     this.action = action;
+    this.priority = (action != null ? action.getPriority() : LOW);
   }
 
   @Override public void run() {
@@ -192,20 +201,59 @@ void attach(Action action) {
     if (loggingEnabled) {
       log(OWNER_HUNTER, VERB_JOINED, request.logId(), getLogIdsForHunter(this, "to "));
     }
+
+    Priority actionPriority = action.getPriority();
+    if (actionPriority.ordinal() > priority.ordinal()) {
+      priority = actionPriority;
+    }
   }
 
   void detach(Action action) {
+    boolean detached = false;
     if (this.action == action) {
       this.action = null;
+      detached = true;
     } else if (actions != null) {
-      actions.remove(action);
+      detached = actions.remove(action);
+    }
+
+    // The action being detached had the highest priority. Update this
+    // hunter's priority with the remaining actions.
+    if (detached && action.getPriority() == priority) {
+      priority = computeNewPriority();
     }
 
     if (picasso.loggingEnabled) {
       log(OWNER_HUNTER, VERB_REMOVED, action.request.logId(), getLogIdsForHunter(this, "from "));
     }
   }
 
+  private Priority computeNewPriority() {
+    Priority newPriority = LOW;
+
+    boolean hasMultiple = actions != null && !actions.isEmpty();
+
+    // Hunter has no requests, low priority.
+    if (actions == null && !hasMultiple) {
+      return newPriority;
+    }
+
+    if (action != null) {
+      newPriority = action.getPriority();
+    }
+
+    if (hasMultiple) {
+      for (int i = 0, n = actions.size(); i < n; i++) {
+        Priority actionPriority = actions.get(i).getPriority();
+        if (actionPriority.ordinal() > newPriority.ordinal()) {
+          newPriority = actionPriority;
+        }
+      }
+    }
+
+    return newPriority;
+  }
+
   boolean cancel() {
     return action == null
         && (actions == null || actions.isEmpty())
@@ -266,6 +314,10 @@ Picasso.LoadedFrom getLoadedFrom() {
     return loadedFrom;
   }
 
+  Priority getPriority() {
+    return priority;
+  }
+
   static void updateThreadName(Request data) {
     String name = data.getName();
 

picasso/src/main/java/com/squareup/picasso/Picasso.java

@@ -88,6 +88,17 @@ public interface RequestTransformer {
     };
   }
 
+  /**
+   * The priority of a request.
+   *
+   * @see RequestCreator#priority(Priority)
+   */
+  public enum Priority {
+    LOW,
+    NORMAL,
+    HIGH
+  }
+
   static final String TAG = "Picasso";
   static final Handler HANDLER = new Handler(Looper.getMainLooper()) {
     @Override public void handleMessage(Message msg) {

picasso/src/main/java/com/squareup/picasso/PicassoExecutorService.java

@@ -18,7 +18,10 @@
 import android.net.ConnectivityManager;
 import android.net.NetworkInfo;
 import android.telephony.TelephonyManager;
-import java.util.concurrent.LinkedBlockingQueue;
+
+import java.util.concurrent.Future;
+import java.util.concurrent.FutureTask;
+import java.util.concurrent.PriorityBlockingQueue;
 import java.util.concurrent.ThreadPoolExecutor;
 import java.util.concurrent.TimeUnit;
 
@@ -33,7 +36,7 @@ class PicassoExecutorService extends ThreadPoolExecutor {
 
   PicassoExecutorService() {
     super(DEFAULT_THREAD_COUNT, DEFAULT_THREAD_COUNT, 0, TimeUnit.MILLISECONDS,
-        new LinkedBlockingQueue<Runnable>(), new Utils.PicassoThreadFactory());
+        new PriorityBlockingQueue<Runnable>(), new Utils.PicassoThreadFactory());
   }
 
   void adjustThreadCount(NetworkInfo info) {
@@ -78,4 +81,31 @@ private void setThreadCount(int threadCount) {
     setCorePoolSize(threadCount);
     setMaximumPoolSize(threadCount);
   }
+
+  @Override
+  public Future<?> submit(Runnable task) {
+    PicassoFutureTask ftask = new PicassoFutureTask((BitmapHunter) task);
+    execute(ftask);
+    return ftask;
+  }
+
+  private static final class PicassoFutureTask extends FutureTask<BitmapHunter>
+      implements Comparable<PicassoFutureTask> {
+    private final BitmapHunter hunter;
+
+    public PicassoFutureTask(BitmapHunter hunter) {
+      super(hunter, null);
+      this.hunter = hunter;
+    }
+
+    @Override
+    public int compareTo(PicassoFutureTask other) {
+      Picasso.Priority p1 = hunter.getPriority();
+      Picasso.Priority p2 = other.hunter.getPriority();
+
+      // High-priority requests are "lesser" so they are sorted to the front.
+      // Equal priorities are sorted by sequence number to provide FIFO ordering.
+      return (p1 == p2 ? hunter.sequence - other.hunter.sequence : p2.ordinal() - p1.ordinal());
+    }
+  }
 }

picasso/src/main/java/com/squareup/picasso/Request.java

@@ -17,6 +17,7 @@
 
 import android.graphics.Bitmap;
 import android.net.Uri;
+import com.squareup.picasso.Picasso.Priority;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.TimeUnit;
@@ -74,10 +75,13 @@ public final class Request {
   public final boolean hasRotationPivot;
   /** Target image config for decoding. */
   public final Bitmap.Config config;
+  /** The priority of this request. */
+  public final Priority priority;
 
   private Request(Uri uri, int resourceId, List<Transformation> transformations, int targetWidth,
       int targetHeight, boolean centerCrop, boolean centerInside, float rotationDegrees,
-      float rotationPivotX, float rotationPivotY, boolean hasRotationPivot, Bitmap.Config config) {
+      float rotationPivotX, float rotationPivotY, boolean hasRotationPivot, Bitmap.Config config,
+      Priority priority) {
     this.uri = uri;
     this.resourceId = resourceId;
     if (transformations == null) {
@@ -94,6 +98,7 @@ private Request(Uri uri, int resourceId, List<Transformation> transformations, i
     this.rotationPivotY = rotationPivotY;
     this.hasRotationPivot = hasRotationPivot;
     this.config = config;
+    this.priority = priority;
   }
 
   @Override public String toString() {
@@ -185,6 +190,7 @@ public static final class Builder {
     private boolean hasRotationPivot;
     private List<Transformation> transformations;
     private Bitmap.Config config;
+    private Priority priority;
 
     /** Start building a request using the specified {@link Uri}. */
     public Builder(Uri uri) {
@@ -216,6 +222,7 @@ private Builder(Request request) {
         transformations = new ArrayList<Transformation>(request.transformations);
       }
       config = request.config;
+      priority = request.priority;
     }
 
     boolean hasImage() {
@@ -226,6 +233,10 @@ boolean hasSize() {
       return targetWidth != 0;
     }
 
+    boolean hasPriority() {
+      return priority != null;
+    }
+
     /**
      * Set the target image Uri.
      * <p>
@@ -343,6 +354,18 @@ public Builder config(Bitmap.Config config) {
       return this;
     }
 
+    /** Execute request using the specified priority. */
+    public Builder priority(Priority priority) {
+      if (priority == null) {
+        throw new IllegalArgumentException("Priority invalid.");
+      }
+      if (this.priority != null) {
+        throw new IllegalStateException("Priority already set.");
+      }
+      this.priority = priority;
+      return this;
+    }
+
     /**
      * Add a custom transformation to be applied to the image.
      * <p>
@@ -370,8 +393,12 @@ public Request build() {
       if (centerInside && targetWidth == 0) {
         throw new IllegalStateException("Center inside requires calling resize.");
       }
+      if (priority == null) {
+        priority = Priority.NORMAL;
+      }
       return new Request(uri, resourceId, transformations, targetWidth, targetHeight, centerCrop,
-          centerInside, rotationDegrees, rotationPivotX, rotationPivotY, hasRotationPivot, config);
+          centerInside, rotationDegrees, rotationPivotX, rotationPivotY, hasRotationPivot, config,
+          priority);
     }
   }
 }

picasso/src/main/java/com/squareup/picasso/RequestCreator.java

@@ -30,6 +30,7 @@
 
 import static com.squareup.picasso.BitmapHunter.forRequest;
 import static com.squareup.picasso.Picasso.LoadedFrom.MEMORY;
+import static com.squareup.picasso.Picasso.Priority;
 import static com.squareup.picasso.PicassoDrawable.setBitmap;
 import static com.squareup.picasso.PicassoDrawable.setPlaceholder;
 import static com.squareup.picasso.RemoteViewsAction.AppWidgetAction;
@@ -228,6 +229,18 @@ public RequestCreator config(Bitmap.Config config) {
     return this;
   }
 
+  /**
+   * Set the priority of this request.
+   * <p>
+   * This will affect the order in which the requests execute but does not guarantee it.
+   * By default, all requests have {@link Priority#NORMAL} priority, except for
+   * {@link #fetch()} requests, which have {@link Priority#LOW} priority by default.
+   */
+  public RequestCreator priority(Priority priority) {
+    data.priority(priority);
+    return this;
+  }
+
   /**
    * Add a custom transformation to be applied to the image.
    * <p>
@@ -292,6 +305,11 @@ public void fetch() {
       throw new IllegalStateException("Fit cannot be used with fetch.");
     }
     if (data.hasImage()) {
+      // Fetch requests have lower priority by default.
+      if (!data.hasPriority()) {
+        data.priority(Priority.LOW);
+      }
+
       Request request = createRequest(started);
       String key = createKey(request, new StringBuilder());