1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #ifndef mozilla_SynchronizedEventQueue_h
8 #define mozilla_SynchronizedEventQueue_h
10 #include "mozilla/AlreadyAddRefed.h"
11 #include "mozilla/EventQueue.h"
12 #include "mozilla/MemoryReporting.h"
13 #include "mozilla/Mutex.h"
14 #include "nsIThreadInternal.h"
16 #include "nsTObserverArray.h"
19 class nsISerialEventTarget
;
20 class nsIThreadObserver
;
24 // A SynchronizedEventQueue is an abstract class for event queues that can be
25 // used across threads. A SynchronizedEventQueue implementation will typically
26 // use locks and condition variables to guarantee consistency. The methods of
27 // SynchronizedEventQueue are split between ThreadTargetSink (which contains
28 // methods for posting events) and SynchronizedEventQueue (which contains
29 // methods for getting events). This split allows event targets (specifically
30 // ThreadEventTarget) to use a narrow interface, since they only need to post
33 // ThreadEventQueue is the canonical implementation of
34 // SynchronizedEventQueue. When Quantum DOM is implemented, we will use a
35 // different synchronized queue on the main thread, SchedulerEventQueue, which
36 // will handle the cooperative threading model.
38 class ThreadTargetSink
{
40 NS_INLINE_DECL_THREADSAFE_REFCOUNTING(ThreadTargetSink
)
42 virtual bool PutEvent(already_AddRefed
<nsIRunnable
>&& aEvent
,
43 EventQueuePriority aPriority
) = 0;
45 // After this method is called, no more events can be posted.
46 virtual void Disconnect(const MutexAutoLock
& aProofOfLock
) = 0;
48 size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf
) const {
49 return aMallocSizeOf(this) + SizeOfExcludingThis(aMallocSizeOf
);
52 virtual size_t SizeOfExcludingThis(
53 mozilla::MallocSizeOf aMallocSizeOf
) const = 0;
56 virtual ~ThreadTargetSink() = default;
59 class SynchronizedEventQueue
: public ThreadTargetSink
{
61 virtual already_AddRefed
<nsIRunnable
> GetEvent(
62 bool aMayWait
, mozilla::TimeDuration
* aLastEventDelay
= nullptr) = 0;
63 virtual bool HasPendingEvent() = 0;
65 // This method atomically checks if there are pending events and, if there are
66 // none, forbids future events from being posted. It returns true if there
67 // were no pending events.
68 virtual bool ShutdownIfNoPendingEvents() = 0;
70 // These methods provide access to an nsIThreadObserver, whose methods are
71 // called when posting and processing events. SetObserver should only be
72 // called on the thread that processes events. GetObserver can be called from
73 // any thread. GetObserverOnThread must be used from the thread that processes
74 // events; it does not acquire a lock.
75 virtual already_AddRefed
<nsIThreadObserver
> GetObserver() = 0;
76 virtual already_AddRefed
<nsIThreadObserver
> GetObserverOnThread() = 0;
77 virtual void SetObserver(nsIThreadObserver
* aObserver
) = 0;
79 void AddObserver(nsIThreadObserver
* aObserver
);
80 void RemoveObserver(nsIThreadObserver
* aObserver
);
81 const nsTObserverArray
<nsCOMPtr
<nsIThreadObserver
>>& EventObservers();
83 size_t SizeOfExcludingThis(
84 mozilla::MallocSizeOf aMallocSizeOf
) const override
{
85 return mEventObservers
.ShallowSizeOfExcludingThis(aMallocSizeOf
);
89 * This method causes any events currently enqueued on the thread to be
90 * suppressed until PopEventQueue is called, and any event dispatched to this
91 * thread's nsIEventTarget will queue as well. Calls to PushEventQueue may be
92 * nested and must each be paired with a call to PopEventQueue in order to
93 * restore the original state of the thread. The returned nsIEventTarget may
94 * be used to push events onto the nested queue. Dispatching will be disabled
95 * once the event queue is popped. The thread will only ever process pending
96 * events for the innermost event queue. Must only be called on the target
99 virtual already_AddRefed
<nsISerialEventTarget
> PushEventQueue() = 0;
102 * Revert a call to PushEventQueue. When an event queue is popped, any events
103 * remaining in the queue are appended to the elder queue. This also causes
104 * the nsIEventTarget returned from PushEventQueue to stop dispatching events.
105 * Must only be called on the target thread, and with the innermost event
108 virtual void PopEventQueue(nsIEventTarget
* aTarget
) = 0;
111 virtual ~SynchronizedEventQueue() = default;
114 nsTObserverArray
<nsCOMPtr
<nsIThreadObserver
>> mEventObservers
;
117 } // namespace mozilla
119 #endif // mozilla_SynchronizedEventQueue_h