gecko-dev/xpcom/ds/nsITimelineService.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"

%{C++
#ifdef MOZ_TIMELINE
%}
      
/**
 * nsITimelineService is used to constuct a timeline of program
 * execution.  The timeline is output to a file, either stderr or the
 * value of the environment variable NS_TIMELINE_LOG_FILE.  On the
 * Mac, the timeline is output to the file named "timeline.txt".  The
 * reason it's different on the Mac is that the Mac environment
 * initialization code happens after timeline initialization code.
 * 
 * If NS_TIMELINE_INIT_TIME is set in the environment, that will be
 * used as the time of startup; otherwise the current time when mark()
 * is first called will be used.
 * 
 * mark() is used to put marks on the timeline.
 * 
 * indent() and outdent() are used to format the timeline a bit to
 * show nesting.  This doesn't produce perfect results in the face of
 * asychrony and multiple threads.
 * 
 * enter() and leave() are convenience functions that add marks to the
 * timeline and do indentation.
 * 
 * startTimer() and stopTimer() control named stop watches.  If
 * startTimer() is called more than once, an equal number of
 * stopTimer() calls are needed to actually stop the timer.  This
 * makes these timers slightly useful in a threaded environment.
 * 
 * markTimer() puts a mark on the timeline containing the total for
 * the named timer.
 * 
 * Don't use nsITimelineService in C++ code; use the NS_TIMELINE
 * macros instead.  nsITimelineService exists so that JavaScript code
 * can mark the timeline.
 */
[scriptable, uuid(93276790-3daf-11d5-b67d-000064657374)]
interface nsITimelineService : nsISupports
{
    /**
     * mark()
     * Print "<elapsed time>: <text>\n" in the timeline log file.
     */
    void mark(in string text);

    /**
     * causes subsequent marks to be indented for a more readable
     * report.
     */
    void indent();

    /**
     * Causes subsequent marks to be outdented.
     */
    void outdent();

    /**
     * enter/leave bracket code with "<text>..." and "...<text>" as
     * well as indentation.
     */
    void enter(in string text);
    void leave(in string text);

    void startTimer(in string timerName);

    void stopTimer(in string timerName);

    void markTimer(in string timerName);
};

%{C++
#endif /* MOZ_TIMELINE */
%}


%{C++

#ifdef MOZ_TIMELINE

/*
 * These are equivalent to the corresponding nsITimelineService
 * methods, and can be called before XPCOM is initialized.
 */
PR_EXTERN(nsresult) NS_TimelineMark(const char *text, ...);
PR_EXTERN(nsresult) NS_TimelineStartTimer(const char *timerName);
PR_EXTERN(nsresult) NS_TimelineStopTimer(const char *timerName);
PR_EXTERN(nsresult) NS_TimelineMarkTimer(const char *timerName);
PR_EXTERN(nsresult) NS_TimelineIndent();
PR_EXTERN(nsresult) NS_TimelineOutdent();
PR_EXTERN(nsresult) NS_TimelineEnter(const char *text);
PR_EXTERN(nsresult) NS_TimelineLeave(const char *text);

/*
 * Use these macros for the above calls so we can easily compile them
 * out.
 */
#define NS_TIMELINE_MARK(text) NS_TimelineMark(text)
#define NS_TIMELINE_MARKV(args) NS_TimelineMark args
#define NS_TIMELINE_INDENT() NS_TimelineIndent()
#define NS_TIMELINE_OUTDENT() NS_TimelineOutdent()
#define NS_TIMELINE_ENTER(text) NS_TimelineEnter(text)
#define NS_TIMELINE_LEAVE(text) NS_TimelineLeave(text)
#define NS_TIMELINE_START_TIMER(timerName) NS_TimelineStartTimer(timerName)
#define NS_TIMELINE_STOP_TIMER(timerName) NS_TimelineStopTimer(timerName)
#define NS_TIMELINE_MARK_TIMER(timerName) NS_TimelineMarkTimer(timerName)

/*
 * NS_TIMELINE_MARK_ macros for various data types.  Each of these
 * macros replaces "%s" in its "text" argument with a string
 * representation of its last argument.
 * 
 * Please feel free to add more NS_TIMELINE_MARK_ macros for
 * various data types so that code using NS_TIMELINE is uncluttered.
 * Don't forget the empty versions in the #else section below for
 * non-timeline builds.
 */
#define NS_TIMELINE_MARK_URI(text, uri) \
    { \
        char *spec = NULL; \
        if (uri) { \
            uri->GetSpec(&spec); \
        } \
        if (spec != NULL) { \
            NS_TimelineMark(text, spec); \
            nsCRT::free(spec); \
        } else { \
            NS_TimelineMark(text, "??"); \
        } \
    }

#define NS_TIMELINE_MARK_CHANNEL(text, channel) \
    { \
        nsCOMPtr<nsIURI> uri; \
        if (channel) { \
            channel->GetURI(getter_AddRefs(uri)); \
        } \
        NS_TIMELINE_MARK_URI(text, uri); \
    }

#define NS_TIMELINE_MARK_LOADER(text, loader) \
    { \
        nsCOMPtr<nsIRequest> request; \
        loader->GetRequest(getter_AddRefs(request)); \
        nsCOMPtr<nsIChannel> channel(do_QueryInterface(request)); \
        NS_TIMELINE_MARK_CHANNEL(text, channel); \
    }

#else /* !defined(MOZ_TIMELINE) */
#define NS_TIMELINE_MARK(text)
#define NS_TIMELINE_MARKV(args)
#define NS_TIMELINE_INDENT()
#define NS_TIMELINE_OUTDENT()
#define NS_TIMELINE_START_TIMER(timerName)
#define NS_TIMELINE_STOP_TIMER(timerName)
#define NS_TIMELINE_MARK_TIMER(timerName)
#define NS_TIMELINE_ENTER(text)
#define NS_TIMELINE_LEAVE(text)
#define NS_TIMELINE_MARK_URI(text, uri)
#define NS_TIMELINE_MARK_CHANNEL(text, channel)
#define NS_TIMELINE_MARK_LOADER(text, loader);
#endif /* defined(MOZ_TIMELINE) */ 
%}