场景介绍

如果应用的业务逻辑比较复杂，可能需要创建多个线程来执行多个任务。这种情况下，代码复杂难以维护，任务与线程的交互也会更加繁杂。要解决此问题，开发者可以使用“TaskDispatcher”来分发不同的任务。

接口说明

TaskDispatcher 是一个任务分发器，它是 Ability 分发任务的基本接口，隐藏任务所在线程的实现细节。

为保证应用有更好的响应性，我们需要设计任务的优先级。在 UI 线程上运行的任务默认以高优先级运行，如果某个任务无需等待结果，则可以用低优先级。

优先级	详细描述
HIGH	最高任务优先级，比默认优先级、低优先级的任务有更高的几率得到执行。
DEFAULT	默认任务优先级， 比低优先级的任务有更高的几率得到执行。
LOW	低任务优先级，比高优先级、默认优先级的任务有更低的几率得到执行。

TaskDispatcher 具有多种实现，每种实现对应不同的任务分发器。在分发任务时可以指定任务的优先级，由同一个任务分发器分发出的任务具有相同的优先级。系统提供的任务分发器有 GlobalTaskDispatcher、ParallelTaskDispatcher、SerialTaskDispatcher 、SpecTaskDispatcher。

• GlobalTaskDispatcher

全局并发任务分发器，由 Ability 执行 getGlobalTaskDispatcher()获取。适用于任务之间没有联系的情况。一个应用只有一个 GlobalTaskDispatcher，它在程序结束时才被销毁。

  TaskDispatcher globalTaskDispatcher = getGlobalTaskDispatcher(TaskPriority.DEFAULT);

• ParallelTaskDispatcher

并发任务分发器，由 Ability 执行 createParallelTaskDispatcher() 创建并返回。与 GlobalTaskDispatcher 不同的是，ParallelTaskDispatcher 不具有全局唯一性，可以创建多个。开发者在创建或销毁 dispatcher 时，需要持有对应的对象引用 。

  String dispatcherName = "parallelTaskDispatcher";
  TaskDispatcher parallelTaskDispatcher = createParallelTaskDispatcher(dispatcherName, TaskPriority.DEFAULT);

• SerialTaskDispatcher

串行任务分发器，由 Ability 执行 createSerialTaskDispatcher()创建并返回。由该分发器分发的所有的任务都是按顺序执行，但是执行这些任务的线程并不是固定的。如果要执行并行任务，应使用 ParallelTaskDispatcher 或者 GlobalTaskDispatcher，而不是创建多个 SerialTaskDispatcher。如果任务之间没有依赖，应使用GlobalTaskDispatcher 来实现。它的创建和销毁由开发者自己管理，开发者在使用期间需要持有该对象引用。

  String dispatcherName = "serialTaskDispatcher";
  TaskDispatcher serialTaskDispatcher = createSerialTaskDispatcher(dispatcherName, TaskPriority.DEFAULT);

• SpecTaskDispatcher

专有任务分发器，绑定到专有线程上的任务分发器。目前已有的专有线程是主线程。 UITaskDispatcher 和 MainTaskDispatcher 都属于 SpecTaskDispatcher。建议使用 UITaskDispatcher。

UITaskDispatcher：绑定到应用主线程的专有任务分发器， 由 Ability 执行 getUITaskDispatcher() 创建并返回。 由该分发器分发的所有的任务都是在主线程上按顺序执行，它在应用程序结束时被销毁。

  TaskDispatcher uiTaskDispatcher = getUITaskDispatcher();

MainTaskDispatcher：由 Ability 执行 getMainTaskDispatcher() 创建并返回。

  TaskDispatcher mainTaskDispatcher= getMainTaskDispatcher()

开发步骤

• syncDispatch

同步派发任务：派发任务并在当前线程等待任务执行完成。在返回前，当前线程会被阻塞。

如下代码示例展示了如何使用 GlobalTaskDispatcher 派发同步任务：

  globalTaskDispatcher.syncDispatch(new Runnable() {
              @Override
              public void run() {
                  HiLog.info(label, "sync task1 run");
              }
          });
  HiLog.info(label, "after sync task1");

   
  globalTaskDispatcher.syncDispatch(new Runnable() {
              @Override
              public void run() {
                  HiLog.info(label, "sync task2 run");
              }
          });
  HiLog.info(label, "after sync task2");

   
  globalTaskDispatcher.syncDispatch(new Runnable() {
              @Override
              public void run() {
                  HiLog.info(label, "sync task3 run");
              }
          });
  HiLog.info(label, "after sync task3");

   
  // 执行结果如下：
  // sync task1 run
  // after sync task1
  // sync task2 run
  // after sync task2
  // sync task3 run
  // after sync task3

说明

如果对 syncDispatch 使用不当, 将会导致死锁。如下情形可能导致死锁发生：

• 在专有线程上，利用该专有任务分发器进行 syncDispatch。
• 在被某个串行任务分发器（dispatcher_a）派发的任务中，再次利用同一个串行任务分发器（dispatcher_a）对象派发任务。
• 在被某个串行任务分发器（dispatcher_a）派发的任务中，经过数次派发任务，最终又利用该（dispatcher_a）串行任务分发器派发任务。例如：dispatcher_a 派发的任务使用 dispatcher_b 进行任务的派发，在 dispatcher_b 派发的任务中又利用 dispatcher_a 进行派发任务。
• 串行任务分发器（dispatcher_a）派发的任务中利用串行任务分发器（dispatcher_b）进行同步派发任务，同时 dispatcher_b 派发的任务中利用串行任务分发器（dispatcher_a）进行同步派发任务。在特定的线程执行顺序下将导致死锁。

• asyncDispatch

异步派发任务：派发任务，并立即返回，返回值是一个可用于取消任务的接口。

如下代码示例展示了如何使用 GlobalTaskDispatcher 派发异步任务：

  Revocable revocable =  globalTaskDispatcher.asyncDispatch(new Runnable() {
          @Override
              public void run() {
                  HiLog.info(label, "async task1 run");
              }
          });
  HiLog.info(label, "after async task1");

   
  // 执行结果可能如下：
  // after async task1
  // async task1 run

• delayDispatch

异步延迟派发任务：异步执行，函数立即返回，内部会在延时指定时间后将任务派发到相应队列中。延时时间参数仅代表在这段时间以后任务分发器会将任务加入到队列中，任务的实际执行时间可能晚于这个时间。具体比这个数值晚多久，取决于队列及内部线程池的繁忙情况。

如下代码示例展示了如何使用 GlobalTaskDispatcher 延迟派发任务：

   final long callTime = System.currentTimeMillis();
   final long delayTime = 50;
   Revocable revocable =  globalTaskDispatcher.delayDispatch(new Runnable() {
              @Override
              public void run() {
                  HiLog.info(label, "delayDispatch task1 run");
                  final long actualDelayMs = System.currentTimeMillis() - callTime;
                  HiLog.info(label, "actualDelayTime >= delayTime : %{public}b" + (actualDelayMs >= delayTime));
              }
          }, delayTime );
   HiLog.info(label, "after delayDispatch task1");

   
  // 执行结果可能如下：
  // after delayDispatch task1
  // delayDispatch task1 run
  // actualDelayTime >= delayTime : true

• Group

任务组：表示一组任务，且该组任务之间有一定的联系，由 TaskDispatcher 执行 createDispatchGroup 创建并返回。将任务加入任务组，返回一个用于取消任务的接口。

如下代码示例展示了任务组的使用方式：将一系列相关联的下载任务放入一个任务组，执行完下载任务后关闭应用。

  void groupTest(Context context) {
      TaskDispatcher dispatcher = context.createParallelTaskDispatcher(dispatcherName, TaskPriority.DEFAULT);
      // 创建任务组。
      Group group = dispatcher.createDispatchGroup();
      // 将任务1加入任务组，返回一个用于取消任务的接口。
      dispatcher.asyncGroupDispatch(group, new Runnable(){
          public void run() {
              HiLog.info(label, "download task1 is running");
              downLoadRes(url1);
          }
      });
     // 将与任务1相关联的任务2加入任务组。
      dispatcher.asyncGroupDispatch(group, new Runnable(){
          public void run() {
              HiLog.info(label, "download task2 is running");
              downLoadRes(url2);
          }
      });
      // 在任务组中的所有任务执行完成后执行指定任务。
      dispatcher.groupDispatchNotify(group, new Runnable(){
          public void run() {
              HiLog.info(label, "the close task is running after all tasks in the group are completed");
              closeApp();
          }
      });
  }
  ​
  // 可能的执行结果:
  // download task1 is running
  // download task2 is running
  // the close task is running after all tasks in the group are completed

   
  // 另外一种可能的执行结果：
  // download task2 is running
  // download task1 is running
  // the close task is running after all tasks in the group are completed

• Revocable

取消任务：Revocable 是取消一个异步任务的接口。异步任务包括通过 asyncDispatch、delayDispatch、asyncGroupDispatch 派发的任务。如果任务已经在执行中或执行完成，则会返回取消失败。

如下代码示例展示了如何取消一个异步延时任务：

  void postTaskAndRevoke(Context context) {
      TaskDispatcher dispatcher = context.getUITaskDispatcher();
      Revocable revocable = dispatcher.delayDispatch(new Runnable(){
           HiLog.info(label, "delay dispatch");
      }, 10);
      boolean revoked = revocable.revoke();
      HiLog.info(label, "%{public}b", revoked);
  }
  ​
  // 一种可能的结果如下 :
  // true

• syncDispatchBarrier

同步设置屏障任务：在任务组上设立任务执行屏障，同步等待任务组中的所有任务执行完成，再执行指定任务。

说明

在全局并发任务分发器（GlobalTaskDispatcher）上同步设置任务屏障，将不会起到屏障作用。

如下代码示例展示了如何同步设置屏障：

      TaskDispatcher dispatcher = context.createParallelTaskDispatcher(dispatcherName, TaskPriority.DEFAULT);
      // 创建任务组。
      Group group = dispatcher.createDispatchGroup();
      // 将任务加入任务组，返回一个用于取消任务的接口。
      dispatcher.asyncGroupDispatch(group, new Runnable(){
          public void run() {
              HiLog.info(label, "task1 is running");  // 1
          }
      });
      dispatcher.asyncGroupDispatch(group, new Runnable(){
          public void run() {
              HiLog.info(label, "task2 is running");  // 2
          }
      });

      
      dispatcher.syncDispatchBarrier(new Runnable() {  
      public void run() {  
          HiLog.info(label, "barrier");  // 3
      }});  
      HiLog.info(label, "after syncDispatchBarrier");  // 4
  }
  ​
  // 1和2的执行顺序不定；3和4总是在1和2之后按顺序执行。

   
  // 可能的执行结果:
  // task1 is running
  // task2 is running
  // barrier
  // after syncDispatchBarrier

   
  // 另外一种执行结果：
  // task2 is running
  // task1 is running
  // barrier
  // after syncDispatchBarrier

• asyncDispatchBarrier

异步设置屏障任务：在任务组上设立任务执行屏障后直接返回，指定任务将在任务组中的所有任务执行完成后再执行。

说明

在全局并发任务分发器（GlobalTaskDispatcher）上异步设置任务屏障，将不会起到屏障作用。可以使用并发任务分发器（ParallelTaskDispatcher）分离不同的任务组，达到微观并行、宏观串行的行为。

如下代码示例展示了如何异步设置屏障：

      TaskDispatcher dispatcher = context.createParallelTaskDispatcher(dispatcherName, TaskPriority.DEFAULT);
      // 创建任务组。
      Group group = dispatcher.createDispatchGroup();
      // 将任务加入任务组，返回一个用于取消任务的接口。
      dispatcher.asyncGroupDispatch(group, new Runnable(){
          public void run() {
              HiLog.info(label, "task1 is running");  // 1
          }
      });
      dispatcher.asyncGroupDispatch(group, new Runnable(){
          public void run() {
              HiLog.info(label, "task2 is running");  // 2
          }
      });

      
      dispatcher.asyncDispatchBarrier(new Runnable() {  
          public void run() {  
              HiLog.info(label, "barrier");  // 3
          }
  });  
      HiLog.info(label, "after syncDispatchBarrier");  // 4
  }
  ​
  // 1和2的执行顺序不定，但总在3和4之前执行；4可能在3之前执行

   
  // 可能的执行结果:
  // task1 is running
  // task2 is running
  // after syncDispatchBarrier
  // barrier 

• applyDispatch

执行多次任务：对指定任务执行多次。

如下代码示例展示了如何执行多次任务：

   final int total = 10;
   final CountDownLatch latch = new CountDownLatch(total);
   final ArrayList<Long> indexList = new ArrayList<>(total);

   
   // 执行任务 total 次
   dispatcher.applyDispatch((index) -> {
       indexList.add(index);
       latch.countDown();
   }, total);

   
   // 设置任务超时
   try {    
       latch.await();
   } catch (InterruptedException exception) {
      HiLog.info(label, "latch exception");
   }
   HiLog.info(label, "list size matches, %{public}b", (total == indexList.size()));

   
  // 执行结果：
  // list size matches, true