зеркало из https://github.com/mozilla/gecko-dev.git
Bug 951855: Improve documentation for nsICycleCollectionListener and nsICycleCollectionHandler. r=smaug
This commit is contained in:
Родитель
b40f160398
Коммит
4837e42f09
|
@ -4,6 +4,33 @@
|
|||
|
||||
#include "nsISupports.idl"
|
||||
|
||||
/**
|
||||
* Interfaces for observing the cycle collector's work, both from C++ and
|
||||
* from JavaScript.
|
||||
*
|
||||
* If given an object implementing nsICycleCollectorListener, the cycle
|
||||
* collector calls that object's methods as it works, describing the
|
||||
* objects it visits, the edges it finds, and the conclusions it reaches
|
||||
* about which objects are live.
|
||||
*
|
||||
* Analyzing cycle collection from JS is harder: an nsICycleCollectorListener
|
||||
* mustn't mess with the object graph while the cycle collector is trying to
|
||||
* figure it out, which means it can't be implemented by JS code: JS can't do
|
||||
* much of anything useful within those constraints. Instead, JS code can
|
||||
* instantiate @mozilla.org/cycle-collector-logger;1, a C++ class implementing
|
||||
* nsICycleCollectorListener that logs the cycle collector's mumblings and then
|
||||
* replays them later to an nsICycleCollectorHandler --- which *can* be
|
||||
* implemented in JS.
|
||||
*/
|
||||
|
||||
/**
|
||||
* The interface JS code should implement to receive annotations logged by an
|
||||
* @mozilla.org/cycle-collector-logger;1 instance. Pass an instance of this to
|
||||
* the logger's 'processNext' method.
|
||||
*
|
||||
* The methods are a subset of those in nsICycleCollectorListener; see the
|
||||
* descriptions there.
|
||||
*/
|
||||
[scriptable, uuid(39a8f80e-7eee-4141-b9ef-6e2a7d6e466d)]
|
||||
interface nsICycleCollectorHandler : nsISupports
|
||||
{
|
||||
|
@ -22,35 +49,92 @@ interface nsICycleCollectorHandler : nsISupports
|
|||
void describeGarbage(in ACString aAddress);
|
||||
};
|
||||
|
||||
/** Interface to pass to the cycle collector to get information about
|
||||
* the CC graph while it's being built. The order of calls will be a
|
||||
* call to begin(); then for every node in the graph a call to either
|
||||
* noteRefCountedObject() or noteGCedObject(), followed by calls to
|
||||
* noteEdge() for every edge starting at that node. Then, there may
|
||||
* be calls to noteIncrementalRoot(). After that, beginResults() will
|
||||
* be called, followed by a mixture of describeRoot() for ref counted
|
||||
* nodes the CC has identified as roots and describeGarbage() for
|
||||
* nodes the CC has identified as garbage. Ref counted nodes that are
|
||||
* not identified as either roots or garbage are neither, and have a
|
||||
* known edges count equal to their ref count. Finally, there will be
|
||||
* a call to end(). If begin() returns an error none of the other
|
||||
* functions will be called.
|
||||
/**
|
||||
* Given an instance of this interface, the cycle collector calls the instance's
|
||||
* methods to report the objects it visits, the edges between them, and its
|
||||
* conclusions about which objects are roots and which are garbage.
|
||||
*
|
||||
* For a single cycle collection pass, the cycle collector calls this
|
||||
* interface's methods in the following order:
|
||||
*
|
||||
* - First, |begin|. If |begin| returns an error, none of the listener's other
|
||||
* methods will be called.
|
||||
*
|
||||
* - Then, for each node in the graph:
|
||||
* - a call to either |noteRefCountedObject| or |noteGCedObject|, to describe
|
||||
* the node itself; and
|
||||
* - for each edge starting at that node, a call to |noteEdge|.
|
||||
*
|
||||
* - Then, zero or more calls to |noteIncrementalRoot|; an "incremental
|
||||
* root" is an object that may have had a new reference to it created
|
||||
* during an incremental collection, and must therefore be treated as
|
||||
* live for safety.
|
||||
*
|
||||
* - After all the nodes have been described, a call to |beginResults|.
|
||||
*
|
||||
* - A series of calls to:
|
||||
* - |describeRoot|, for reference-counted nodes that the CC has identified as
|
||||
* roots of collection. (The cycle collector didn't find enough incoming
|
||||
* edges to account for these nodes' reference counts, so there must be code
|
||||
* holding on to them that the cycle collector doesn't know about.)
|
||||
* - |describeGarbage|, for nodes the cycle collector has identified as garbage.
|
||||
*
|
||||
* Any node not mentioned in a call to |describeRoot| or |describeGarbage| is
|
||||
* neither a root nor garbage. (The cycle collector was able to find all the
|
||||
* edges implied by the node's reference count.)
|
||||
*
|
||||
* - Finally, a call to |end|.
|
||||
*
|
||||
*
|
||||
* This interface cannot be implemented by JavaScript code, as it is called
|
||||
* while the cycle collector works. To analyze cycle collection data in JS:
|
||||
*
|
||||
* - Create an instance of @mozilla.org/cycle-collector-logger;1, which
|
||||
* implements this interface.
|
||||
*
|
||||
* - Set its |disableLog| property to true. This prevents the logger from
|
||||
* printing messages about each method call to a temporary log file.
|
||||
*
|
||||
* - Set its |wantAfterProcessing| property to true. This tells the logger
|
||||
* to record calls to its methods in memory. The |processNext| method
|
||||
* returns events from this record.
|
||||
*
|
||||
* - Perform a collection using the logger. For example, call
|
||||
* |nsIDOMWindowUtils|'s |garbageCollect| method, passing the logger as
|
||||
* the |aListener| argument.
|
||||
*
|
||||
* - When the collection is complete, loop calling the logger's
|
||||
* |processNext| method, passing a JavaScript object that implements
|
||||
* nsICycleCollectorHandler. This JS code is free to allocate and operate
|
||||
* on objects however it pleases: the cycle collector has finished its
|
||||
* work, and the JS code is simply consuming recorded data.
|
||||
*/
|
||||
[scriptable, builtinclass, uuid(2d04dd00-abc4-11e3-a5e2-0800200c9a66)]
|
||||
[scriptable, builtinclass, uuid(c46e6947-9076-4a0e-bb27-d4aa3706c54d)]
|
||||
interface nsICycleCollectorListener : nsISupports
|
||||
{
|
||||
// Return a listener that directs the cycle collector to traverse objects
|
||||
// that it knows won't be collectable. If your purpose is to build a picture
|
||||
// of the heap, and not simply find garbage, then you should use the
|
||||
// listener this returns.
|
||||
//
|
||||
// Note that this does not necessarily return a new listener; rather, it may
|
||||
// simply set a flag on this listener (a side effect!) and return it.
|
||||
nsICycleCollectorListener allTraces();
|
||||
// false if allTraces() has not been called.
|
||||
|
||||
// True if this listener will behave like one returned by allTraces().
|
||||
readonly attribute boolean wantAllTraces;
|
||||
|
||||
// The default implementation of this interface will print out
|
||||
// a log to a file unless disableLog is set to true.
|
||||
// If true, do not log each method call to a temporary file.
|
||||
// Initially false.
|
||||
attribute boolean disableLog;
|
||||
attribute boolean wantAfterProcessing;
|
||||
|
||||
// This string will appear somewhere in the log's filename.
|
||||
attribute AString filenameIdentifier;
|
||||
|
||||
// If true, record all method calls in memory, to be retrieved later
|
||||
// using |processNext|. Initially false.
|
||||
attribute boolean wantAfterProcessing;
|
||||
|
||||
// This string will indicate the full path of the GC log if enabled.
|
||||
readonly attribute AString gcLogPath;
|
||||
|
||||
|
@ -71,9 +155,6 @@ interface nsICycleCollectorListener : nsISupports
|
|||
in unsigned long long aKey,
|
||||
in unsigned long long aKeyDelegate,
|
||||
in unsigned long long aValue);
|
||||
// An "incremental root" is an object that may have had a new
|
||||
// reference to it created during an incremental collection,
|
||||
// and must therefore be treated as live for safety.
|
||||
void noteIncrementalRoot(in unsigned long long aAddress);
|
||||
|
||||
void beginResults();
|
||||
|
@ -82,6 +163,10 @@ interface nsICycleCollectorListener : nsISupports
|
|||
void describeGarbage(in unsigned long long aAddress);
|
||||
void end();
|
||||
|
||||
// Returns false if there isn't anything more to process.
|
||||
// Report the next recorded event to |aHandler|, and remove it from the
|
||||
// record. Return false if there isn't anything more to process.
|
||||
//
|
||||
// Note that we only record events to report here if our
|
||||
// |wantAfterProcessing| property is true.
|
||||
boolean processNext(in nsICycleCollectorHandler aHandler);
|
||||
};
|
||||
|
|
Загрузка…
Ссылка в новой задаче