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
177
178
179
180
181
182
183
184
185
186
187
188
189
|
// Copyright (c) 2012 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_MESSAGE_LOOP_MESSAGE_PUMP_H_
#define BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_
#include "base/base_export.h"
#include "base/check_op.h"
#include "base/message_loop/message_pump_type.h"
#include "base/message_loop/timer_slack.h"
#include "base/sequence_checker.h"
#include "base/time/time.h"
#include "build/build_config.h"
namespace base {
class TimeTicks;
class BASE_EXPORT MessagePump {
public:
using MessagePumpFactory = std::unique_ptr<MessagePump>();
// Uses the given base::MessagePumpFactory to override the default MessagePump
// implementation for 'MessagePumpType::UI'. May only be called once.
static void OverrideMessagePumpForUIFactory(MessagePumpFactory* factory);
// Returns true if the MessagePumpForUI has been overidden.
static bool IsMessagePumpForUIFactoryOveridden();
// Creates the default MessagePump based on |type|. Caller owns return value.
static std::unique_ptr<MessagePump> Create(MessagePumpType type);
// Please see the comments above the Run method for an illustration of how
// these delegate methods are used.
class BASE_EXPORT Delegate {
public:
virtual ~Delegate() = default;
// Called before a unit of work internal to the message pump is executed.
// This allows reports about individual units of work to be produced. The
// unit of work ends when BeforeDoInternalWork() is called again, or when
// BeforeWait(), DoWork(), or DoIdleWork() is called.
// TODO(crbug.com/851163): Place calls for all platforms.
virtual void BeforeDoInternalWork() = 0;
// Called before the message pump starts waiting for work.
// This indicates the end of the current unit of work, which is required
// to produce reports about individual units of work.
virtual void BeforeWait() = 0;
struct NextWorkInfo {
// Helper to extract a TimeDelta for pumps that need a
// timeout-till-next-task.
TimeDelta remaining_delay() const {
DCHECK(!delayed_run_time.is_null() && !delayed_run_time.is_max());
DCHECK_GE(TimeTicks::Now(), recent_now);
return delayed_run_time - recent_now;
}
// Helper to verify if the next task is ready right away.
bool is_immediate() const { return delayed_run_time.is_null(); }
// The next PendingTask's |delayed_run_time|. is_null() if there's extra
// work to run immediately. is_max() if there are no more immediate nor
// delayed tasks.
TimeTicks delayed_run_time;
// A recent view of TimeTicks::Now(). Only valid if |next_task_run_time|
// isn't null nor max. MessagePump impls should use remaining_delay()
// instead of resampling Now() if they wish to sleep for a TimeDelta.
TimeTicks recent_now;
};
// Executes an immediate task or a ripe delayed task. Returns information
// about when DoWork() should be called again. If the returned NextWorkInfo
// is_immediate(), DoWork() must be invoked again shortly. Else, DoWork()
// must be invoked at |NextWorkInfo::delayed_run_time| or when
// ScheduleWork() is invoked, whichever comes first. Redundant/spurious
// invocations of DoWork() outside of those requirements are tolerated.
// DoIdleWork() will not be called so long as this returns a NextWorkInfo
// which is_immediate().
virtual NextWorkInfo DoWork() = 0;
// Called from within Run just before the message pump goes to sleep.
// Returns true to indicate that idle work was done. Returning false means
// the pump will now wait.
virtual bool DoIdleWork() = 0;
};
MessagePump();
virtual ~MessagePump();
// The Run method is called to enter the message pump's run loop.
//
// Within the method, the message pump is responsible for processing native
// messages as well as for giving cycles to the delegate periodically. The
// message pump should take care to mix delegate callbacks with native message
// processing so neither type of event starves the other of cycles. Each call
// to a delegate function or DoInternalWork() is considered the beginning of a
// new "unit of work".
//
// The anatomy of a typical run loop:
//
// for (;;) {
// bool did_internal_work = DoInternalWork();
// if (should_quit_)
// break;
//
// Delegate::NextWorkInfo next_work_info = delegate->DoWork();
// if (should_quit_)
// break;
//
// if (did_internal_work || next_work_info.is_immediate())
// continue;
//
// bool did_idle_work = delegate_->DoIdleWork();
// if (should_quit_)
// break;
//
// if (did_idle_work)
// continue;
//
// WaitForWork();
// }
//
// Here, DoInternalWork is some private method of the message pump that is
// responsible for dispatching the next UI message or notifying the next IO
// completion (for example). WaitForWork is a private method that simply
// blocks until there is more work of any type to do.
//
// Notice that the run loop cycles between calling DoInternalWork and DoWork
// methods. This helps ensure that none of these work queues starve the
// others. This is important for message pumps that are used to drive
// animations, for example.
//
// Notice also that after each callout to foreign code, the run loop checks to
// see if it should quit. The Quit method is responsible for setting this
// flag. No further work is done once the quit flag is set.
//
// NOTE 1: Run may be called reentrantly from any of the callouts to foreign
// code (internal work, DoWork, DoIdleWork). As a result, DoWork and
// DoIdleWork must be reentrant.
//
// NOTE 2: Run implementations must arrange for DoWork to be invoked as
// expected if a callout to foreign code enters a message pump outside their
// control. For example, the MessageBox API on Windows pumps UI messages. If
// the MessageBox API is called (indirectly) from within Run, it is expected
// that DoWork will be invoked from within that call in response to
// ScheduleWork or as requested by the last NextWorkInfo returned by DoWork.
// The MessagePump::Delegate may then elect to do nested work or not depending
// on its policy in that context. Regardless of that decision (and return
// value of the nested DoWork() call), DoWork() will be invoked again when the
// nested loop unwinds.
virtual void Run(Delegate* delegate) = 0;
// Quit immediately from the most recently entered run loop. This method may
// only be used on the thread that called Run.
virtual void Quit() = 0;
// Schedule a DoWork callback to happen reasonably soon. Does nothing if a
// DoWork callback is already scheduled. Once this call is made, DoWork is
// guaranteed to be called repeatedly at least until it returns a
// non-immediate NextWorkInfo. This call can be expensive and callers should
// attempt not to invoke it again before a non-immediate NextWorkInfo was
// returned from DoWork(). Thread-safe (and callers should avoid holding a
// Lock at all cost while making this call as some platforms' priority
// boosting features have been observed to cause the caller to get descheduled
// : https://crbug.com/890978).
virtual void ScheduleWork() = 0;
// Schedule a DoWork callback to happen at the specified time, cancelling any
// pending callback scheduled by this method. This method may only be used on
// the thread that called Run.
//
// It isn't necessary to call this during normal execution, as the pump wakes
// up as requested by the return value of DoWork().
// TODO(crbug.com/885371): Determine if this must be called to ensure that
// delayed tasks run when a message pump outside the control of Run is
// entered.
virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time) = 0;
// Sets the timer slack to the specified value.
virtual void SetTimerSlack(TimerSlack timer_slack);
};
} // namespace base
#endif // BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_
|
