/* 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(0ef15f15-7783-4991-af68-4976d7ec2267)]
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);
    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 a call to
 * beginResults(); then 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(4282249c-7f80-4093-b620-96c573ad683e)]
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;

    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);
    void noteEdge(in unsigned long long aToAddress,
                  in string aEdgeName);
    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);
};