/* 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/. */

#include "nsISupports.idl"

[scriptable, uuid(39a8f80e-7eee-4141-b9ef-6e2a7d6e466d)]
interface nsICycleCollectorHandler : nsISupports
{
    void noteRefCountedObject(in ACString aAddress,
                              in unsigned long aRefCount,
                              in ACString aObjectDescription);
    void noteGCedObject(in ACString aAddress,
                        in boolean aMarked,
                        in ACString aObjectDescription,
                        in ACString aCompartmentAddress);
    void noteEdge(in ACString aFromAddress,
                  in ACString aToAddress,
                  in ACString aEdgeName);
    void describeRoot(in ACString aAddress,
                      in unsigned long aKnownEdges);
    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.
 */
[scriptable, builtinclass, uuid(2d04dd00-abc4-11e3-a5e2-0800200c9a66)]
interface nsICycleCollectorListener : nsISupports
{
    nsICycleCollectorListener allTraces();
    // false if allTraces() has not been called.
    readonly attribute boolean wantAllTraces;

    // The default implementation of this interface will print out
    // a log to a file unless disableLog is set to true.
    attribute boolean disableLog;
    attribute boolean wantAfterProcessing;

    // This string will appear somewhere in the log's filename.
    attribute AString filenameIdentifier;

    // This string will indicate the full path of the GC log if enabled.
    readonly attribute AString gcLogPath;

    // This string will indicate the full path of the CC log if enabled.
    readonly attribute AString ccLogPath;

    void begin();
    void noteRefCountedObject (in unsigned long long aAddress,
			       in unsigned long aRefCount,
			       in string aObjectDescription);
    void noteGCedObject (in unsigned long long aAddress,
			 in boolean aMarked,
			 in string aObjectDescription,
			 in unsigned long long aCompartmentAddress);
    void noteEdge(in unsigned long long aToAddress,
                  in string aEdgeName);
    void noteWeakMapEntry(in unsigned long long aMap,
                          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();
    void describeRoot(in unsigned long long aAddress,
		      in unsigned long aKnownEdges);
    void describeGarbage(in unsigned long long aAddress);
    void end();

    // Returns false if there isn't anything more to process.
    boolean processNext(in nsICycleCollectorHandler aHandler);
};
