OLD | NEW |
1 // Copyright 2016 The Chromium Authors. All rights reserved. | 1 // Copyright 2016 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef BASE_TASK_SCHEDULER_POST_TASK_H_ | 5 #ifndef BASE_TASK_SCHEDULER_POST_TASK_H_ |
6 #define BASE_TASK_SCHEDULER_POST_TASK_H_ | 6 #define BASE_TASK_SCHEDULER_POST_TASK_H_ |
7 | 7 |
8 #include "base/base_export.h" | 8 #include "base/base_export.h" |
9 #include "base/callback_forward.h" | 9 #include "base/callback_forward.h" |
10 #include "base/location.h" | 10 #include "base/location.h" |
11 #include "base/memory/ref_counted.h" | 11 #include "base/memory/ref_counted.h" |
| 12 #include "base/sequenced_task_runner.h" |
| 13 #include "base/single_thread_task_runner.h" |
12 #include "base/task_runner.h" | 14 #include "base/task_runner.h" |
13 #include "base/task_scheduler/task_traits.h" | 15 #include "base/task_scheduler/task_traits.h" |
14 | 16 |
15 namespace base { | 17 namespace base { |
16 | 18 |
17 // This is the preferred interface to post tasks to the TaskScheduler. | 19 // This is the preferred interface to post tasks to the TaskScheduler. |
18 // | 20 // |
19 // Note: The TaskScheduler is still in an experimental phase in Chrome. Please | 21 // Note: The TaskScheduler is still in an experimental phase in Chrome. Please |
20 // refrain from using this API unless you know what you are doing. | 22 // refrain from using this API unless you know what you are doing. |
21 // | 23 // |
22 // TaskScheduler must have been registered for the current process via | 24 // TaskScheduler must have been registered for the current process via |
23 // TaskScheduler::SetInstance() before the functions below are valid. | 25 // TaskScheduler::SetInstance() before the functions below are valid. |
24 // | 26 // |
25 // To post a simple one-off task: | 27 // To post a simple one-off task: |
26 // PostTask(FROM_HERE, Bind(...)); | 28 // PostTask(FROM_HERE, Bind(...)); |
27 // | 29 // |
28 // To post a high priority one-off task to respond to a user interaction: | 30 // To post a high priority one-off task to respond to a user interaction: |
29 // PostTaskWithTraits( | 31 // PostTaskWithTraits( |
30 // FROM_HERE, | 32 // FROM_HERE, |
31 // TaskTraits().WithPriority(TaskPriority::USER_BLOCKING), | 33 // TaskTraits().WithPriority(TaskPriority::USER_BLOCKING), |
32 // Bind(...)); | 34 // Bind(...)); |
33 // | 35 // |
34 // To post tasks that must run in sequence: | 36 // To post tasks that must run in sequence: |
35 // scoped_refptr<TaskRunner> task_runner = CreateTaskRunnerWithTraits( | 37 // scoped_refptr<SequencedTaskRunner> task_runner = |
36 // TaskTraits(), ExecutionMode::SEQUENCED); | 38 // CreateSequencedTaskRunnerWithTraits(TaskTraits()); |
37 // task_runner.PostTask(FROM_HERE, Bind(...)); | 39 // task_runner.PostTask(FROM_HERE, Bind(...)); |
38 // task_runner.PostTask(FROM_HERE, Bind(...)); | 40 // task_runner.PostTask(FROM_HERE, Bind(...)); |
39 // | 41 // |
40 // To post file I/O tasks that must run in sequence and can be skipped on | 42 // To post file I/O tasks that must run in sequence and can be skipped on |
41 // shutdown: | 43 // shutdown: |
42 // scoped_refptr<TaskRunner> task_runner = | 44 // scoped_refptr<SequencedTaskRunner> task_runner = |
43 // CreateTaskRunnerWithTraits( | 45 // CreateSequencedTaskRunnerWithTraits( |
44 // TaskTraits().WithFileIO().WithShutdownBehavior( | 46 // TaskTraits().WithFileIO().WithShutdownBehavior( |
45 // TaskShutdownBehavior::SKIP_ON_SHUTDOWN), | 47 // TaskShutdownBehavior::SKIP_ON_SHUTDOWN)); |
46 // ExecutionMode::SEQUENCED); | |
47 // task_runner.PostTask(FROM_HERE, Bind(...)); | 48 // task_runner.PostTask(FROM_HERE, Bind(...)); |
48 // task_runner.PostTask(FROM_HERE, Bind(...)); | 49 // task_runner.PostTask(FROM_HERE, Bind(...)); |
49 // | 50 // |
50 // The default TaskTraits apply to tasks that: | 51 // The default TaskTraits apply to tasks that: |
51 // (1) don't need to do I/O, | 52 // (1) don't need to do I/O, |
52 // (2) don't affect user interaction and/or visible elements, and | 53 // (2) don't affect user interaction and/or visible elements, and |
53 // (3) can either block shutdown or be skipped on shutdown | 54 // (3) can either block shutdown or be skipped on shutdown |
54 // (barring current TaskScheduler default). | 55 // (barring current TaskScheduler default). |
55 // If those loose requirements are sufficient for your task, use | 56 // If those loose requirements are sufficient for your task, use |
56 // PostTask[AndReply], otherwise override these with explicit traits via | 57 // PostTask[AndReply], otherwise override these with explicit traits via |
(...skipping 21 matching lines...) Expand all Loading... |
78 // Posts |task| with specific |traits| to the TaskScheduler and posts |reply| on | 79 // Posts |task| with specific |traits| to the TaskScheduler and posts |reply| on |
79 // the caller's execution context (i.e. same sequence or thread and same | 80 // the caller's execution context (i.e. same sequence or thread and same |
80 // TaskTraits if applicable) when |task| completes. Can only be called when | 81 // TaskTraits if applicable) when |task| completes. Can only be called when |
81 // SequencedTaskRunnerHandle::IsSet(). | 82 // SequencedTaskRunnerHandle::IsSet(). |
82 BASE_EXPORT void PostTaskWithTraitsAndReply( | 83 BASE_EXPORT void PostTaskWithTraitsAndReply( |
83 const tracked_objects::Location& from_here, | 84 const tracked_objects::Location& from_here, |
84 TaskTraits traits, | 85 TaskTraits traits, |
85 const Closure& task, | 86 const Closure& task, |
86 const Closure& reply); | 87 const Closure& reply); |
87 | 88 |
88 // Returns a TaskRunner whose PostTask invocations will result in scheduling | 89 // Returns a TaskRunner whose PostTask invocations result in scheduling tasks |
89 // tasks using |traits| which will be executed according to |execution_mode|. | 90 // using |traits|. Tasks may run in any order and in parallel. |
90 BASE_EXPORT scoped_refptr<TaskRunner> CreateTaskRunnerWithTraits( | 91 BASE_EXPORT scoped_refptr<TaskRunner> CreateTaskRunnerWithTraits( |
91 TaskTraits traits, | 92 const TaskTraits& traits); |
92 ExecutionMode execution_mode); | 93 |
| 94 // Returns a SequencedTaskRunner whose PostTask invocations result in scheduling |
| 95 // tasks using |traits|. Tasks run one at a time in posting order. |
| 96 BASE_EXPORT scoped_refptr<SequencedTaskRunner> |
| 97 CreateSequencedTaskRunnerWithTraits(const TaskTraits& traits); |
| 98 |
| 99 // Returns a SingleThreadTaskRunner whose PostTask invocations result in |
| 100 // scheduling tasks using |traits|. Tasks run on a single thread in posting |
| 101 // order. |
| 102 // |
| 103 // If all you need is to make sure that tasks don't run concurrently (e.g. |
| 104 // because they access a data structure which is not thread-safe), use |
| 105 // CreateSequencedTaskRunnerWithTraits(). Only use this if you rely on a thread- |
| 106 // affine API (it might be safer to assume thread-affinity when dealing with |
| 107 // under-documented third-party APIs, e.g. other OS') or share data across tasks |
| 108 // using thread-local storage. |
| 109 BASE_EXPORT scoped_refptr<SingleThreadTaskRunner> |
| 110 CreateSingleThreadTaskRunnerWithTraits(const TaskTraits& traits); |
93 | 111 |
94 } // namespace base | 112 } // namespace base |
95 | 113 |
96 #endif // BASE_TASK_SCHEDULER_POST_TASK_H_ | 114 #endif // BASE_TASK_SCHEDULER_POST_TASK_H_ |
OLD | NEW |