1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef BASE_TASK_SCHEDULER_POST_TASK_H_
#define BASE_TASK_SCHEDULER_POST_TASK_H_
#include <utility>
#include "base/base_export.h"
#include "base/bind.h"
#include "base/callback.h"
#include "base/location.h"
#include "base/memory/ref_counted.h"
#include "base/post_task_and_reply_with_result_internal.h"
#include "base/sequenced_task_runner.h"
#include "base/single_thread_task_runner.h"
#include "base/task_runner.h"
#include "base/task_scheduler/task_traits.h"
#include "base/time/time.h"
namespace base {
// This is the preferred interface to post tasks to the TaskScheduler.
//
// To post a simple one-off task with default traits:
// PostTask(FROM_HERE, Bind(...));
//
// To post a high priority one-off task to respond to a user interaction:
// PostTaskWithTraits(
// FROM_HERE,
// TaskTraits().WithPriority(TaskPriority::USER_BLOCKING),
// Bind(...));
//
// To post tasks that must run in sequence with default traits:
// scoped_refptr<SequencedTaskRunner> task_runner =
// CreateSequencedTaskRunnerWithTraits(TaskTraits());
// task_runner.PostTask(FROM_HERE, Bind(...));
// task_runner.PostTask(FROM_HERE, Bind(...));
//
// To post tasks that may block, must run in sequence and can be skipped on
// shutdown:
// scoped_refptr<SequencedTaskRunner> task_runner =
// CreateSequencedTaskRunnerWithTraits(
// TaskTraits().MayBlock().WithShutdownBehavior(
// TaskShutdownBehavior::SKIP_ON_SHUTDOWN));
// task_runner.PostTask(FROM_HERE, Bind(...));
// task_runner.PostTask(FROM_HERE, Bind(...));
//
// The default traits apply to tasks that:
// (1) don't block (ref. MayBlock() and WithBaseSyncPrimitives()),
// (2) prefer inheriting the current priority to specifying their own, and
// (3) can either block shutdown or be skipped on shutdown
// (TaskScheduler implementation is free to choose a fitting default).
// Explicit traits must be specified for tasks for which these loose
// requirements are not sufficient.
//
// Tasks posted through functions below will run on threads owned by the
// registered TaskScheduler (i.e. not on the main thread). Tasks posted through
// functions below with a delay may be coalesced (i.e. delays may be adjusted to
// reduce the number of wakeups and hence power consumption).
//
// Prerequisite: A TaskScheduler must have been registered for the current
// process via TaskScheduler::SetInstance() before the functions below are
// valid. This is typically done during the initialization phase in each
// process. If your code is not running in that phase, you most likely don't
// have to worry about this. You will encounter DCHECKs or nullptr dereferences
// if this is violated. For tests, prefer base::test::ScopedTaskScheduler.
// Posts |task| to the TaskScheduler. Calling this is equivalent to calling
// PostTaskWithTraits with plain TaskTraits.
BASE_EXPORT void PostTask(const tracked_objects::Location& from_here,
const Closure& task);
// Posts |task| to the TaskScheduler. |task| will not run before |delay|
// expires. Calling this is equivalent to calling PostDelayedTaskWithTraits with
// plain TaskTraits.
//
// Use PostDelayedTaskWithTraits to specify a BACKGROUND priority if the task
// doesn't have to run as soon as |delay| expires.
BASE_EXPORT void PostDelayedTask(const tracked_objects::Location& from_here,
const Closure& task,
TimeDelta delay);
// Posts |task| to the TaskScheduler and posts |reply| on the caller's execution
// context (i.e. same sequence or thread and same TaskTraits if applicable) when
// |task| completes. Calling this is equivalent to calling
// PostTaskWithTraitsAndReply with plain TaskTraits. Can only be called when
// SequencedTaskRunnerHandle::IsSet().
BASE_EXPORT void PostTaskAndReply(const tracked_objects::Location& from_here,
Closure task,
Closure reply);
// Posts |task| to the TaskScheduler and posts |reply| with the return value of
// |task| as argument on the caller's execution context (i.e. same sequence or
// thread and same TaskTraits if applicable) when |task| completes. Calling this
// is equivalent to calling PostTaskWithTraitsAndReplyWithResult with plain
// TaskTraits. Can only be called when SequencedTaskRunnerHandle::IsSet().
template <typename TaskReturnType, typename ReplyArgType>
void PostTaskAndReplyWithResult(const tracked_objects::Location& from_here,
Callback<TaskReturnType(void)> task,
Callback<void(ReplyArgType)> reply) {
PostTaskWithTraitsAndReplyWithResult(from_here, TaskTraits(), std::move(task),
std::move(reply));
}
// Posts |task| with specific |traits| to the TaskScheduler.
BASE_EXPORT void PostTaskWithTraits(const tracked_objects::Location& from_here,
const TaskTraits& traits,
const Closure& task);
// Posts |task| with specific |traits| to the TaskScheduler. |task| will not run
// before |delay| expires.
//
// Specify a BACKGROUND priority via |traits| if the task doesn't have to run as
// soon as |delay| expires.
BASE_EXPORT void PostDelayedTaskWithTraits(
const tracked_objects::Location& from_here,
const TaskTraits& traits,
const Closure& task,
TimeDelta delay);
// Posts |task| with specific |traits| to the TaskScheduler and posts |reply| on
// the caller's execution context (i.e. same sequence or thread and same
// TaskTraits if applicable) when |task| completes. Can only be called when
// SequencedTaskRunnerHandle::IsSet().
BASE_EXPORT void PostTaskWithTraitsAndReply(
const tracked_objects::Location& from_here,
const TaskTraits& traits,
Closure task,
Closure reply);
// Posts |task| with specific |traits| to the TaskScheduler and posts |reply|
// with the return value of |task| as argument on the caller's execution context
// (i.e. same sequence or thread and same TaskTraits if applicable) when |task|
// completes. Can only be called when SequencedTaskRunnerHandle::IsSet().
template <typename TaskReturnType, typename ReplyArgType>
void PostTaskWithTraitsAndReplyWithResult(
const tracked_objects::Location& from_here,
const TaskTraits& traits,
Callback<TaskReturnType()> task,
Callback<void(ReplyArgType)> reply) {
TaskReturnType* result = new TaskReturnType();
return PostTaskWithTraitsAndReply(
from_here, traits, Bind(&internal::ReturnAsParamAdapter<TaskReturnType>,
std::move(task), result),
Bind(&internal::ReplyAdapter<TaskReturnType, ReplyArgType>,
std::move(reply), Owned(result)));
}
// Returns a TaskRunner whose PostTask invocations result in scheduling tasks
// using |traits|. Tasks may run in any order and in parallel.
BASE_EXPORT scoped_refptr<TaskRunner> CreateTaskRunnerWithTraits(
const TaskTraits& traits);
// Returns a SequencedTaskRunner whose PostTask invocations result in scheduling
// tasks using |traits|. Tasks run one at a time in posting order.
BASE_EXPORT scoped_refptr<SequencedTaskRunner>
CreateSequencedTaskRunnerWithTraits(const TaskTraits& traits);
// Returns a SingleThreadTaskRunner whose PostTask invocations result in
// scheduling tasks using |traits|. Tasks run on a single thread in posting
// order.
//
// If all you need is to make sure that tasks don't run concurrently (e.g.
// because they access a data structure which is not thread-safe), use
// CreateSequencedTaskRunnerWithTraits(). Only use this if you rely on a thread-
// affine API (it might be safer to assume thread-affinity when dealing with
// under-documented third-party APIs, e.g. other OS') or share data across tasks
// using thread-local storage.
BASE_EXPORT scoped_refptr<SingleThreadTaskRunner>
CreateSingleThreadTaskRunnerWithTraits(const TaskTraits& traits);
} // namespace base
#endif // BASE_TASK_SCHEDULER_POST_TASK_H_
|
