The Tor Browser: js/public/TracingAPI.h@925c144e1f1f (annotated)

js/public/TracingAPI.h@925c144e1f1f (annotated)

js/public/TracingAPI.h

Fri, 16 Jan 2015 18:13:44 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Fri, 16 Jan 2015 18:13:44 +0100
branch: TOR_BUG_9701
changeset 14: 925c144e1f1f
permissions: -rw-r--r--

Integrate suggestion from review to improve consistency with existing code.

 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  * vim: set ts=8 sts=4 et sw=4 tw=99:
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 #ifndef js_TracingAPI_h
 #define js_TracingAPI_h
 #include "mozilla/NullPtr.h"
 #include "jspubtd.h"
 class JS_PUBLIC_API(JSTracer);
 namespace JS {
 template <typename T> class Heap;
 template <typename T> class TenuredHeap;
 }
 // Tracer callback, called for each traceable thing directly referenced by a
 // particular object or runtime structure. It is the callback responsibility
 // to ensure the traversal of the full object graph via calling eventually
 // JS_TraceChildren on the passed thing. In this case the callback must be
 // prepared to deal with cycles in the traversal graph.
 //
 // kind argument is one of JSTRACE_OBJECT, JSTRACE_STRING or a tag denoting
 // internal implementation-specific traversal kind. In the latter case the only
 // operations on thing that the callback can do is to call JS_TraceChildren or
 // JS_GetTraceThingInfo.
 //
 // If eagerlyTraceWeakMaps is true, when we trace a WeakMap visit all
 // of its mappings. This should be used in cases where the tracer
 // wants to use the existing liveness of entries.
 typedef void
 (* JSTraceCallback)(JSTracer *trc, void **thingp, JSGCTraceKind kind);
 // Callback that JSTraceOp implementation can provide to return a string
 // describing the reference traced with JS_CallTracer.
 typedef void
 (* JSTraceNamePrinter)(JSTracer *trc, char *buf, size_t bufsize);
 enum WeakMapTraceKind {
     DoNotTraceWeakMaps = 0,
     TraceWeakMapValues = 1,
     TraceWeakMapKeysValues = 2
 };
 class JS_PUBLIC_API(JSTracer)
 {
   public:
     JSTracer(JSRuntime *rt, JSTraceCallback traceCallback,
              WeakMapTraceKind weakTraceKind = TraceWeakMapValues);
     // Set debugging information about a reference to a traceable thing to prepare
     // for the following call to JS_CallTracer.
     //
     // When printer is null, arg must be const char * or char * C string naming
     // the reference and index must be either (size_t)-1 indicating that the name
     // alone describes the reference or it must be an index into some array vector
     // that stores the reference.
     //
     // When printer callback is not null, the arg and index arguments are
     // available to the callback as debugPrintArg_ and debugPrintIndex_ fields
     // of JSTracer.
     //
     // The storage for name or callback's arguments needs to live only until
     // the following call to JS_CallTracer returns.
     void setTracingDetails(JSTraceNamePrinter printer, const void *arg, size_t index) {
         debugPrinter_ = printer;
         debugPrintArg_ = arg;
         debugPrintIndex_ = index;
     }
     void setTracingIndex(const char *name, size_t index) {
         setTracingDetails(nullptr, (void *)name, index);
     }
     void setTracingName(const char *name) {
         setTracingDetails(nullptr, (void *)name, size_t(-1));
     }
     // Remove the currently set tracing details.
     void clearTracingDetails() {
         debugPrinter_ = nullptr;
         debugPrintArg_ = nullptr;
     }
     // Return true if tracing details are currently set.
     bool hasTracingDetails() const;
     // Get the string set with the most recent call to setTracingName or return
     // fallback if a name printer function has been installed.
     const char *tracingName(const char *fallback) const;
     // Build a description of this edge in the heap graph. This call may invoke
     // the debug printer, which may inspect arbitrary areas of the heap.
     const char *getTracingEdgeName(char *buffer, size_t bufferSize);
     // Access the currently active tracing details.
     JSTraceNamePrinter debugPrinter() const;
     const void *debugPrintArg() const;
     size_t debugPrintIndex() const;
     // Return the runtime set on the tracer.
     JSRuntime *runtime() const { return runtime_; }
     // Return the weak map tracing behavior set on this tracer.
     WeakMapTraceKind eagerlyTraceWeakMaps() const { return eagerlyTraceWeakMaps_; }
     // Update the trace callback.
     void setTraceCallback(JSTraceCallback traceCallback);
 #ifdef JS_GC_ZEAL
     // Sets the "real" location for a marked reference, when passing the address
     // directly is not feasable. This address is used for matching against the
     // store buffer when verifying the correctness of the entrees there.
     //
     // This is currently complicated by our need to nest calls for Values
     // stored as keys in hash tables.
     void setTracingLocation(void *location);
     void unsetTracingLocation();
     void **tracingLocation(void **thingp);
 #else
     void setTracingLocation(void *location) {}
     void unsetTracingLocation() {}
     void **tracingLocation(void **thingp) { return nullptr; }
 #endif
     // We expose |callback| directly so that IS_GC_MARKING_TRACER can compare
     // it to GCMarker::GrayCallback.
     JSTraceCallback     callback;
   private:
     JSRuntime           *runtime_;
     JSTraceNamePrinter  debugPrinter_;
     const void          *debugPrintArg_;
     size_t              debugPrintIndex_;
     WeakMapTraceKind    eagerlyTraceWeakMaps_;
 #ifdef JS_GC_ZEAL
     void                *realLocation_;
 #endif
 };
 // The JS_Call*Tracer family of functions traces the given GC thing reference.
 // This performs the tracing action configured on the given JSTracer:
 // typically calling the JSTracer::callback or marking the thing as live.
 //
 // The argument to JS_Call*Tracer is an in-out param: when the function
 // returns, the garbage collector might have moved the GC thing. In this case,
 // the reference passed to JS_Call*Tracer will be updated to the object's new
 // location. Callers of this method are responsible for updating any state
 // that is dependent on the object's address. For example, if the object's
 // address is used as a key in a hashtable, then the object must be removed
 // and re-inserted with the correct hash.
 //
 extern JS_PUBLIC_API(void)
 JS_CallValueTracer(JSTracer *trc, JS::Value *valuep, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallIdTracer(JSTracer *trc, jsid *idp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallObjectTracer(JSTracer *trc, JSObject **objp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallStringTracer(JSTracer *trc, JSString **strp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallScriptTracer(JSTracer *trc, JSScript **scriptp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallHeapValueTracer(JSTracer *trc, JS::Heap<JS::Value> *valuep, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallHeapIdTracer(JSTracer *trc, JS::Heap<jsid> *idp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallHeapObjectTracer(JSTracer *trc, JS::Heap<JSObject *> *objp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallHeapStringTracer(JSTracer *trc, JS::Heap<JSString *> *strp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallHeapScriptTracer(JSTracer *trc, JS::Heap<JSScript *> *scriptp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_CallHeapFunctionTracer(JSTracer *trc, JS::Heap<JSFunction *> *funp, const char *name);
 template <typename HashSetEnum>
 inline void
 JS_CallHashSetObjectTracer(JSTracer *trc, HashSetEnum &e, JSObject *const &key, const char *name)
 {
     JSObject *updated = key;
     trc->setTracingLocation(reinterpret_cast<void *>(&const_cast<JSObject *&>(key)));
     JS_CallObjectTracer(trc, &updated, name);
     if (updated != key)
         e.rekeyFront(key, updated);
 }
 // Trace an object that is known to always be tenured.  No post barriers are
 // required in this case.
 extern JS_PUBLIC_API(void)
 JS_CallTenuredObjectTracer(JSTracer *trc, JS::TenuredHeap<JSObject *> *objp, const char *name);
 extern JS_PUBLIC_API(void)
 JS_TraceChildren(JSTracer *trc, void *thing, JSGCTraceKind kind);
 extern JS_PUBLIC_API(void)
 JS_TraceRuntime(JSTracer *trc);
 extern JS_PUBLIC_API(void)
 JS_GetTraceThingInfo(char *buf, size_t bufsize, JSTracer *trc,
                      void *thing, JSGCTraceKind kind, bool includeDetails);
 #endif /* js_TracingAPI_h */

The Tor Browser / annotate

js/public/TracingAPI.h@925c144e1f1f (annotated)

js/public/TracingAPI.h