Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(279)

Side by Side Diff: third_party/WebKit/Source/platform/bindings/TraceWrapperReference.md

Issue 2851563004: Add documentation for platform/bindings (Closed)
Patch Set: Code review Created 3 years, 7 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
1 # Wrapper Tracing Reference 1 # Wrapper Tracing Reference
2 2
3 This document describes wrapper tracing and how its API is supposed to be used. 3 This document describes wrapper tracing and how its API is supposed to be used.
4 4
5 [TOC] 5 [TOC]
6 6
7 ## Quickstart guide 7 ## Quickstart guide
8 8
9 Wrapper tracing is used to represent reachability across V8 and Blink. The 9 Wrapper tracing is used to represent reachability across V8 and Blink. The
10 following checklist highlights the modifications needed to make a class 10 following checklist highlights the modifications needed to make a class
11 participate in wrapper tracing. 11 participate in wrapper tracing.
12 12
13 1. Make sure that objects participating in tracing either inherit from 13 1. Make sure that objects participating in tracing either inherit from
14 ``ScriptWrappable`` (if they can reference wrappers) or ``TraceWrapperBase`` 14 ``ScriptWrappable`` (if they can reference wrappers) or ``TraceWrapperBase``
15 (transitively holding wrappers alive). 15 (transitively holding wrappers alive).
16 2. Use ``TraceWrapperMember<T>`` to annotate fields that need to be followed to 16 2. Use ``TraceWrapperMember<T>`` to annotate fields that need to be followed to
17 find other wrappers that this object should keep alive. 17 find other wrappers that this object should keep alive.
18 3. Use ``TraceWrapperV8Reference<T>`` to annotate references to V8 that this 18 3. Use ``TraceWrapperV8Reference<T>`` to annotate references to V8 that this
19 object should keep alive. 19 object should keep alive.
20 4. Declare a method to trace other wrappers using 20 4. Declare a method to trace other wrappers using
21 ``DECLARE_VIRTUAL_TRACE_WRAPPERS()``. 21 ``DECLARE_VIRTUAL_TRACE_WRAPPERS()``.
22 5. Define the method using ``DEFINE_TRACE_WRAPPERS(ClassName)``. 22 5. Define the method using ``DEFINE_TRACE_WRAPPERS(ClassName)``.
23 6. Trace all fields that received a wrapper tracing type in (1) and (2) using 23 6. Trace all fields that received a wrapper tracing type in (1) and (2) using
24 ``visitor->traceWrapers(<m_field>)`` in the body of ``DEFINE_TRACE_WRAPPERS``. 24 ``visitor->traceWrapers(<m_field>)`` in the body of ``DEFINE_TRACE_WRAPPERS``.
25 25
26 The following example illustrates these steps: 26 The following example illustrates these steps:
27 27
28 ```c++ 28 ```c++
29 #include "bindings/core/v8/ScriptWrappable.h" 29 #include "platform/bindings/ScriptWrappable.h"
30 #include "bindings/core/v8/TraceWrapperMember.h" 30 #include "platform/bindings/TraceWrapperMember.h"
31 #include "bindings/core/v8/TraceWrapperV8Reference.h" 31 #include "platform/bindings/TraceWrapperV8Reference.h"
32 32
33 class SomeDOMObject : public ScriptWrappable { // (1) 33 class SomeDOMObject : public ScriptWrappable { // (1)
34 public: 34 public:
35 DECLARE_VIRTUAL_TRACE_WRAPPERS(); // (4) 35 DECLARE_VIRTUAL_TRACE_WRAPPERS(); // (4)
36 36
37 private: 37 private:
38 TraceWrapperMember<OtherWrappable> m_otherWrappable; // (2) 38 TraceWrapperMember<OtherWrappable> m_otherWrappable; // (2)
39 Member<NonWrappable> m_nonWrappable; 39 Member<NonWrappable> m_nonWrappable;
40 TraceWrapperV8Reference<v8::Value> m_v8object; // (3) 40 TraceWrapperV8Reference<v8::Value> m_v8object; // (3)
41 // ... 41 // ...
(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after
74 74
75 [object-grouping-slides]: https://docs.google.com/presentation/d/1I6leiRm0ysSTqy 7QWh33Gfp7_y4ngygyM2tDAqdF0fI/ 75 [object-grouping-slides]: https://docs.google.com/presentation/d/1I6leiRm0ysSTqy 7QWh33Gfp7_y4ngygyM2tDAqdF0fI/
76 [oilpan-docs]: https://chromium.googlesource.com/chromium/src/+/master/third_par ty/WebKit/Source/platform/heap/BlinkGCAPIReference.md 76 [oilpan-docs]: https://chromium.googlesource.com/chromium/src/+/master/third_par ty/WebKit/Source/platform/heap/BlinkGCAPIReference.md
77 77
78 ## Basic usage 78 ## Basic usage
79 79
80 The annotations that are required can be found in the following header files. 80 The annotations that are required can be found in the following header files.
81 Pick the header file depending on what types are needed. 81 Pick the header file depending on what types are needed.
82 82
83 ```c++ 83 ```c++
84 #include "bindings/core/v8/ScriptWrappable.h" 84 #include "platform/bindings/ScriptWrappable.h"
85 #include "bindings/core/v8/TraceWrapperBase.h" 85 #include "platform/bindings/TraceWrapperMember.h"
86 #include "bindings/core/v8/TraceWrapperMember.h" 86 #include "platform/bindings/TraceWrapperV8Reference.h"
87 #include "bindings/core/v8/TraceWrapperV8Reference.h"
88 ``` 87 ```
89 88
90 The following example will guide through the modifications that are needed to 89 The following example will guide through the modifications that are needed to
91 adjust a given class ``SomeDOMObject`` to participate in wrapper tracing. 90 adjust a given class ``SomeDOMObject`` to participate in wrapper tracing.
92 91
93 ```c++ 92 ```c++
94 class SomeDOMObject : public ScriptWrappable { 93 class SomeDOMObject : public ScriptWrappable {
95 // ... 94 // ...
96 private: 95 private:
97 Member<OtherWrappable /* extending ScriptWrappable */> m_otherWrappable; 96 Member<OtherWrappable /* extending ScriptWrappable */> m_otherWrappable;
(...skipping 181 matching lines...) Expand 10 before | Expand all | Expand 10 after
279 DECLARE_VIRTUAL_TRACE_WRAPPERS(); 278 DECLARE_VIRTUAL_TRACE_WRAPPERS();
280 private: 279 private:
281 Member<OtherWrappable>> m_otherWrappable; 280 Member<OtherWrappable>> m_otherWrappable;
282 }; 281 };
283 282
284 DEFINE_TRACE_WRAPPERS(ManualWrappable) { 283 DEFINE_TRACE_WRAPPERS(ManualWrappable) {
285 for (auto other : m_otherWrappables) 284 for (auto other : m_otherWrappables)
286 visitor->traceWrappersWithManualWriteBarrier(other); 285 visitor->traceWrappersWithManualWriteBarrier(other);
287 } 286 }
288 ``` 287 ```
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698