程序包 ohos.app.dispatcher

接口 TaskDispatcher

public interface TaskDispatcher

A basic interface that posts tasks into a task dispatcher.

TaskDispatcher conceals details of low-level thread implementation, including creating, destroying, and reusing.

TaskDispatcher enables execution of synchronous, asynchronous, serial, and parallel tasks in almost all scenarios.

The following example shows how to use this interface to post tasks to the UI thread:

 void postTaskToUI(Context context) {
     TaskDispatcher dispatcher = context.getUITaskDispatcher();

     System.out.println("1");

     dispatcher.delayDispatch(new Runnable() {
         System.out.println("delay dispatch");
     }, 10);

     System.out.println("2");

     dispatcher.asyncDispatch(new Runnable() {
         System.out.println("async dispatch");
     });

     System.out.println("3");

     dispatcher.syncDispatch(new Runnable() {
         System.out.println("sync dispatch");
     });

     System.out.println("4");
 }

 // possible result is:
 // 1
 // 2
 // 3
 // async dispatch
 // sync dispatch
 // 4
 // delay dispatch
 
 

Note: TaskDispatcher has multiple implementations for different purposes.

• ParallelTaskDispatcher (created by createParallelTaskDispatcher) enables abilities to execute parallel tasks. Different from GlobalTaskDispatcher, this task dispatcher is not globally unique. You can create multiple ParallelTaskDispatcher objects.
• SerialTaskDispatcher (created by createSerialTaskDispatcher) enables abilities to execute serial tasks. The thread where a particular task is running, however, is not fixed. If you want to execute tasks in parallel, use a ParallelTaskDispatcher instead of creating multiple SerialTaskDispatcher instances.
• SpecTaskDispatcher (returned by getUITaskDispatcher or getMainTaskDispatcher) is a dispatcher dedicated to a specific thread.

Note

Deadlock: If syncDispatch is incorrectly used, a deadlock occurs in the following scenarios:

1. syncDispatch is called for dispatching a task to a dedicated task dispatcher on a thread that is bound to the dispatcher.
2. syncDispatch is called for dispatching a task to a serial task dispatcher on a thread that is currently being used by a task posted by the dispatcher.
3. syncDispatch is repeatedly called for dispatching a task to various dispatchers but the task is finally dispatched to the first serial task dispatcher.
4. Serial task dispatcher A uses syncDispatch to dispatch a task to serial task dispatcher B, while dispatcher B is using syncDispatch to dispatch a task to dispatcher A. A deadlock occurs in a particular thread execution sequence.
5. The thread pool is fully occupied.

Lifecycle: The lifecycle of a task dispatcher includes three parts:

1. The lifecycle of a dedicated task dispatcher changes with that of an application or ability.
2. Global task dispatchers are lazy initialized and will not be destroyed until an application is terminated.
3. Serial and parallel task dispatcher objects are managed by developers.

从以下版本开始:

1

方法概要

限定符和类型	方法	说明
void	applyDispatch(Consumer<Long> task, long iterations)	Executes a task multiple times without waiting.
Revocable	asyncDispatch(Runnable task)	Asynchronously dispatches a task.
void	asyncDispatchBarrier(Runnable task)	Sets an execution barrier for the given task to be executed only after all tasks in the task group are finished.
Revocable	asyncGroupDispatch(Group group, Runnable task)	Adds a task to a task group asynchronously.
Group	createDispatchGroup()	Creates a task group.
Revocable	delayDispatch(Runnable task, long delayMs)	Dispatches a task after the given delay.
void	groupDispatchNotify(Group group, Runnable task)	Executes a task after all tasks in the task group are finished.
boolean	groupDispatchWait(Group group, long timeout)	Waits all tasks in a task group to finish.
void	syncDispatch(Runnable task)	Dispatches a task and waits until the task is complete in the current thread.
void	syncDispatchBarrier(Runnable task)	Sets an execution barrier in a task group for the given task and waits for the task to be executed after all tasks in the task group are finished.

方法详细资料

syncDispatch

void syncDispatch(Runnable task)

Dispatches a task and waits until the task is complete in the current thread.

The current thread is blocked before the given task is complete. Therefore, a deadlock occurs in the following cases:

1. syncDispatch is cyclically called on a serial task dispatcher or a task dispatcher that is dedicated to a specific thread. For example, syncDispatch is called to dispatch a task from dispatcher A to dispatcher A, or to dispatch a task from dispatcher A to dispatcher B and then back to dispatcher A.
2. Too many threads are blocked on syncDispatch. As a result, the internal thread pool is used up and cannot process other tasks any more.

参数:

task - Indicates the task to be executed. This parameter includes all information required for the task execution.

抛出:

NullPointerException - Throws this exception if the input parameter task is null.

从以下版本开始:

1

asyncDispatch

Revocable asyncDispatch(Runnable task)

Asynchronously dispatches a task.

This method dispatches a task and returns a value immediately without waiting for the task to execute.

参数:

task - Indicates the task to be executed. This parameter includes all information required for the task execution.

返回:

Returns a Revocable instance used for revoking the given task if it has not been invoked.

抛出:

NullPointerException - Throws this exception if the input parameter task is null.

从以下版本开始:

1

delayDispatch

Revocable delayDispatch(Runnable task,
                        long delayMs)

Dispatches a task after the given delay.

This is an asynchronous execution and returns a value immediately without waiting. The task will be dispatched to the queue after the given delay specified by delayMs, and its actual execution time maybe later than the given time. The time when the task will be executed depends on the length of the queue and how busy the thread pool is.

参数:

task - Indicates the task to be executed. This parameter includes all information required for the task execution.

delayMs - Indicates the time period that the given task has to wait before being dispatched.

返回:

Returns a Revocable instance used for revoking the given task if it has not been invoked.

抛出:

NullPointerException - Throws this exception if the input parameter task is null.

从以下版本开始:

1

syncDispatchBarrier

void syncDispatchBarrier(Runnable task)

Sets an execution barrier in a task group for the given task and waits for the task to be executed after all tasks in the task group are finished.

The current thread is blocked until the given task is complete. Incorrect use of this method may cause a deadlock. If too many threads are blocked, resources in the thread pool will be used up.

参数:

task - Indicates the task to be executed.

抛出:

NullPointerException - Throws this exception if the input parameter task is null.

从以下版本开始:

1

asyncDispatchBarrier

void asyncDispatchBarrier(Runnable task)

Sets an execution barrier for the given task to be executed only after all tasks in the task group are finished. This method does not wait for the given task to execute.

Task execution barriers are unavailable on global task dispatchers. Example code for setting a task execution barrier:

 TaskDispatcher parallelTaskDispatcher = context.createParallelTaskDispatcher(null);
 parallelTaskDispatcher.asyncDispatch(new Runnable() {
     public void run() {
         Thread.sleep(1000);   // sleep enough time
         System.out.println("before barrier");
     }}, 0);
 parallelTaskDispatcher.asyncDispatchBarrier(new Runnable() {
     public void run() {
         System.out.println("Barrier");
     }}, 0);
 parallelTaskDispatcher.asyncDispatch(() -> {
     System.out.println("after barrier");
 }, 0);

 // Result will be:
 // before barrier
 // Barrier
 // after barrier
 
 

参数:

task - Indicates the task to be executed. This parameter includes all information required for the task execution.

抛出:

NullPointerException - Throws this exception if the input parameter task is null.

从以下版本开始:

1

createDispatchGroup

Group createDispatchGroup()

Creates a task group.

The Group object returned by this method does not contain any task. If you need to dispatch tasks asynchronously, you can use asyncGroupDispatch(ohos.app.dispatcher.Group, java.lang.Runnable) to associate this object with multiple tasks for monitoring the execution progress of all these tasks.

Example code for waiting for the completion of all download tasks in a task group:

 
 void groupTest(Context context) {
     TaskDispatcher dispatcher = context.createParallelTaskDispatcher();
     // Creates a task group.
     Group group = context.createDispatchGroup();
     // Adds asynchronous tasks to the task group.
     dispatcher.asyncGroupDispatch(group, () -> {
         // Downloads a 10 MB file.
         download(url1);
         System.out.println("Finished downloading URL 1");
     });

     System.out.println("1");

     dispatcher.asyncGroupDispatch(group, () -> {
         // Downloads a 1 MB file.
         download(url2);
         System.out.println("Finished downloading URL 2");
     });

     // Executes a new task until all tasks in the task group are complete.
     dispatcher.groupDispatchNotify(group, () -> {
         System.out.println("All tasks finished. Do shutdown.");
     };
     System.out.println("2");
 }

 //Possible results are as follows:
 // 1
 // 2
 // Finished downloading URL 2
 // Finished downloading URL 1
 // All tasks finished. Do shutdown.
 

返回:

Returns a Group object.

从以下版本开始:

1

asyncGroupDispatch

Revocable asyncGroupDispatch(Group group,
                             Runnable task)

Adds a task to a task group asynchronously.

This method returns a value immediately without waiting for the task to execute.

参数:

group - Indicates the group to which the task is added.

task - Indicates the task to be executed. This parameter includes all information required for the task execution.

返回:

Returns a Revocable instance used for revoking the given task if it has not been invoked.

抛出:

NullPointerException - Throws this exception if the input parameter task or group is null.

从以下版本开始:

1

groupDispatchWait

boolean groupDispatchWait(Group group,
                          long timeout)

Waits all tasks in a task group to finish.

参数:

group - Indicates the task group containing the waiting tasks.

timeout - Indicates the maximum waiting time for a task.

返回:

Returns true if all tasks are correctly executed; returns false if any task times out.

抛出:

NullPointerException - Throws this exception if the input parameter group is null.

从以下版本开始:

1

groupDispatchNotify

void groupDispatchNotify(Group group,
                         Runnable task)

Executes a task after all tasks in the task group are finished.

参数:

group - Indicates the task group containing the waiting tasks.

task - Indicates the task to be executed after all tasks are finished.

抛出:

NullPointerException - Throws this exception if the input parameter task or group is null.

从以下版本开始:

1

applyDispatch

void applyDispatch(Consumer<Long> task,
                   long iterations)

Executes a task multiple times without waiting.

Example code:

 String[] names = {"Rafael Nadal", "Novak Djokovic",
         "Stanislas Wawrinka",
         "David Ferrer","Roger Federer",
         "Andy Murray","Tomas Berdych",
         "Juan Martin Del Potro"};
 int num = atp.length;
 TaskDispatcher dispatcher = context.getGlobalTaskDispatcher(TaskPriority.DEFAULT);
 // Concurrently dispatches tasks using names in |names|.
 dispatcher.applyDispatch((i) ->
                             {System.out.print(names[i]);}, num);
 // The result to be returned depends on thread scheduling of the system.
 
 

参数:

task - Indicates the task to be executed. This parameter includes all information required for the task execution.

iterations - Indicates the number of times the task is executed. The value must be a positive integer.

抛出:

NullPointerException - Throws this exception if the input parameter task is null.

IllegalArgumentException - Throws this exception if the input parameter iterations is 0 or a negative number.

从以下版本开始:

1