Changes between Version 6 and Version 7 of JSRootingGuide

Timestamp:

Jun 22, 2014, 12:02:30 AM (10 years ago)

Author:

Yves

Comment:

Adds examples for heap rooting

JSRootingGuide

@@ -39 +39 @@
 TODO: are they going to remove it from the API? Are there use cases where this rooting approach is superior?
 
-Characteristics:
+==== Characteristics:
  * If no RAII approach is used, it can easily cause leaks if the call to Remove*Root() is missing.
  * In some Gecko use cases this can't be used because it can cause cycles and the cycle collector won't know about them (this is not relevant for us because we don't need a cycle collector).
@@ -45 +45 @@
  * Add*Root is slow --> What does this mean in practice?
 
-Guideline:
+==== Guideline:
  * Try to use the other approaches for the moment. We still have to figure out when/if this approach should be used.
+
+
+==== Example
+Check the attached main.cpp for a full working example (including the base class).
+
+{{{
+#!c++
+#ifndef HEAPROOTINGTEST_H_INCLUDED
+#define HEAPROOTINGTEST_H_INCLUDED
+
+using namespace std;
+
+class CHeapRootingTest : CTestClassBase
+{
+public:
+        
+        CHeapRootingTest(JSRuntime* rt, JSContext* cx) : CTestClassBase(rt, cx)
+        {
+                m_HeapValue.setObject(*InitObjectInternal());
+                JS::AddValueRoot(m_cx, &m_HeapValue);
+        }
+        
+        ~CHeapRootingTest()
+        {
+                JSAutoRequest rq(m_cx);
+                JS::RemoveValueRoot(m_cx, &m_HeapValue);
+        }
+        
+        void PrintUsecount()
+        {
+                JSAutoRequest rq(m_cx);
+                if (!m_HeapValue.isObject())
+                        cerr << "Error: m_HeapValue is not an object!" << endl;
+                
+                JS::RootedObject objStack(m_cx, &m_HeapValue.toObject());
+                PrintUsecountBase(objStack);
+        }
+        
+private:
+         JS::Heap<JS::Value> m_HeapValue;
+};
+
+#endif // HEAPROOTINGTEST_H_INCLUDED
+
+}}}
 
 === Using JS::Heap<T> in combination with custom tracers ===
@@ -53 +98 @@
 Note: There are other ways to add a specified trace function (I haven't tested those yet).
 
-Characteristics:
+==== Characteristics:
  * Obviously it's faster to add (and later remove) one function that gets called during GC and loops over many objects than adding (and removing) many objects to the GC root set in a loop.
  * Less memory overhead because storing a pointer to a trace function requires less memory than storing a large number of pointers to GC things.
 
-Guideline:
+==== Guideline:
  * This approach should be used if large numbers of GC things need to be rooted.
 
+==== Example
+Check the attached main.cpp for a full working example (including the base class).
+
+{{{
+#!c++
+#ifndef HEAPROOTINGTEST_H_INCLUDED
+#define HEAPROOTINGTEST_H_INCLUDED
+
+class CHeapRootingTest : CTestClassBase
+{
+public:
+        
+        static void Trace(JSTracer *trc, void *data)
+        {
+                reinterpret_cast<CHeapRootingTest*>(data)->TraceMember(trc);
+        }
+        
+        void TraceMember(JSTracer *trc)
+        {
+                // The JS_Call<T>Tracer family of functions (those without the "Heap" in the name) will be deprecate in the future.
+                JS_CallHeapValueTracer(trc, &m_HeapValue, "m_HeapValue");
+        }
+
+        CHeapRootingTest(JSRuntime* rt, JSContext* cx) : CTestClassBase(rt, cx)
+        {
+                m_HeapValue.setObject(*InitObjectInternal());
+                JS_AddExtraGCRootsTracer(rt, CHeapRootingTest::Trace, this);
+        }
+        
+        ~CHeapRootingTest()
+        {
+                JS_RemoveExtraGCRootsTracer(m_rt, CHeapRootingTest::Trace, this);
+        }
+        
+        void PrintUsecount()
+        {
+                JSAutoRequest rq(m_cx);
+                if (!m_HeapValue.isObject())
+                        cerr << "Error: m_HeapValue is not an object!" << endl;
+                JS::RootedObject objStack(m_cx, &m_HeapValue.toObject());
+                PrintUsecountBase(objStack);
+        }
+        
+private:
+         JS::Heap<JS::Value> m_HeapValue;
+};
+
+#endif // HEAPROOTINGTEST_H_INCLUDED
+}}}
+
 === Using JS::!PersistentRooted<T> ===
 
-Characteristics:
+==== Characteristics:
  * This type both keeps the reference to the GC thing valid when it gets moved and it protects it against garbage collection. 
  * Costs a small memory and CPU performance overhead (stores GC things to be rooted in a linked list internally).
  * It's obviously easier to use, the code looks cleaner and it's less error prone.
 
-Guideline:
+==== Guideline:
  * This approach should be used for small numbers of objects that don't get rooted and unrooted often.
  
+==== Example
+Check the attached main.cpp for a full working example (including the base class).
+
+{{{
+#!c++
+#ifndef HEAPROOTINGTEST_H_INCLUDED
+#define HEAPROOTINGTEST_H_INCLUDED
+
+class CHeapRootingTest : CTestClassBase
+{
+public:
+        
+        CHeapRootingTest(JSRuntime* rt, JSContext* cx) : m_HeapValue(cx), CTestClassBase(rt, cx)
+        {
+                m_HeapValue = JS::ObjectValue(*InitObjectInternal());
+        }
+        
+        void PrintUsecount()
+        {
+                if (!m_HeapValue.get().isObject())
+                        cerr << "Error: m_HeapValue is not an object!" << endl;
+                JS::RootedObject objStack(m_cx, &m_HeapValue.get().toObject());
+                PrintUsecountBase(objStack);
+        }
+        
+private:
+         JS::PersistentRootedValue m_HeapValue;
+};
+
+#endif // HEAPROOTINGTEST_H_INCLUDED
+}}}
 
 == Testing Rooting ==