1/*
2 * Copyright (C) 2008 Apple Inc. All Rights Reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 *
25 */
26
27#pragma once
28
29#include "ContextDestructionObserver.h"
30#include <wtf/Assertions.h>
31#include <wtf/Forward.h>
32#include <wtf/RefCounted.h>
33#include <wtf/Threading.h>
34
35namespace WebCore {
36
37class Document;
38
39enum class ReasonForSuspension {
40 JavaScriptDebuggerPaused,
41 WillDeferLoading,
42 PageCache,
43 PageWillBeSuspended,
44};
45
46class ActiveDOMObject : public ContextDestructionObserver {
47public:
48 // The suspendIfNeeded must be called exactly once after object construction to update
49 // the suspended state to match that of the ScriptExecutionContext.
50 void suspendIfNeeded();
51 void assertSuspendIfNeededWasCalled() const;
52
53 virtual bool hasPendingActivity() const;
54
55 // The canSuspendForDocumentSuspension() function is used by the caller if there is a choice between suspending
56 // and stopping. For example, a page won't be suspended and placed in the back/forward
57 // cache if it contains any objects that cannot be suspended.
58
59 // However, the suspend function will sometimes be called even if canSuspendForDocumentSuspension() returns false.
60 // That happens in step-by-step JS debugging for example - in this case it would be incorrect
61 // to stop the object. Exact semantics of suspend is up to the object in cases like that.
62
63 virtual const char* activeDOMObjectName() const = 0;
64
65 // These three functions must not have a side effect of creating or destroying
66 // any ActiveDOMObject. That means they must not result in calls to arbitrary JavaScript.
67 virtual bool canSuspendForDocumentSuspension() const = 0; // Returning false in canSuspendForDocumentSuspension() will prevent the page from entering the PageCache.
68 virtual void suspend(ReasonForSuspension);
69 virtual void resume();
70
71 // This function must not have a side effect of creating an ActiveDOMObject.
72 // That means it must not result in calls to arbitrary JavaScript.
73 // It can, however, have a side effect of deleting an ActiveDOMObject.
74 virtual void stop();
75
76 template<typename T> void setPendingActivity(T& thisObject)
77 {
78 ASSERT(&thisObject == this);
79 thisObject.ref();
80 ++m_pendingActivityCount;
81 }
82
83 template<typename T> void unsetPendingActivity(T& thisObject)
84 {
85 ASSERT(m_pendingActivityCount > 0);
86 --m_pendingActivityCount;
87 thisObject.deref();
88 }
89
90 template<class T>
91 class PendingActivity : public RefCounted<PendingActivity<T>> {
92 public:
93 explicit PendingActivity(T& thisObject)
94 : m_thisObject(thisObject)
95 {
96 ++(m_thisObject->m_pendingActivityCount);
97 }
98
99 ~PendingActivity()
100 {
101 ASSERT(m_thisObject->m_pendingActivityCount > 0);
102 --(m_thisObject->m_pendingActivityCount);
103 }
104
105 private:
106 Ref<T> m_thisObject;
107 };
108
109 template<class T> Ref<PendingActivity<T>> makePendingActivity(T& thisObject)
110 {
111 ASSERT(&thisObject == this);
112 return adoptRef(*new PendingActivity<T>(thisObject));
113 }
114
115 bool isContextStopped() const;
116
117protected:
118 explicit ActiveDOMObject(ScriptExecutionContext*);
119 explicit ActiveDOMObject(Document*) = delete;
120 explicit ActiveDOMObject(Document&); // Implemented in Document.h
121 virtual ~ActiveDOMObject();
122
123private:
124 unsigned m_pendingActivityCount;
125#if !ASSERT_DISABLED
126 bool m_suspendIfNeededWasCalled;
127 Ref<Thread> m_creationThread { Thread::current() };
128#endif
129};
130
131#if ASSERT_DISABLED
132
133inline void ActiveDOMObject::assertSuspendIfNeededWasCalled() const
134{
135}
136
137#endif
138
139} // namespace WebCore
140