xpcom/ds/nsITimelineService.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 %{C++
  41 #ifdef MOZ_TIMELINE
  42 %}
  43
  44 /**
  45  * nsITimelineService is used to construct a timeline of program
  46  * execution.  The timeline is output to a file, either stderr or the
  47  * value of the environment variable NS_TIMELINE_LOG_FILE.  On the
  48  * Mac, the timeline is output to the file named "timeline.txt".  The
  49  * reason it's different on the Mac is that the Mac environment
  50  * initialization code happens after timeline initialization code.
  51  *
  52  * If NS_TIMELINE_INIT_TIME is set in the environment, that will be
  53  * used as the time of startup; otherwise the current time when mark()
  54  * is first called will be used.
  55  *
  56  * mark() is used to put marks on the timeline.
  57  *
  58  * indent() and outdent() are used to format the timeline a bit to
  59  * show nesting.  This doesn't produce perfect results in the face of
  60  * asychrony and multiple threads.
  61  *
  62  * enter() and leave() are convenience functions that add marks to the
  63  * timeline and do indentation.
  64  *
  65  * startTimer() and stopTimer() control named stop watches.  If
  66  * startTimer() is called more than once, an equal number of
  67  * stopTimer() calls are needed to actually stop the timer.  This
  68  * makes these timers slightly useful in a threaded environment.
  69  *
  70  * markTimer() puts a mark on the timeline containing the total for
  71  * the named timer.
  72  *
  73  * Don't use nsITimelineService in C++ code; use the NS_TIMELINE
  74  * macros instead.  nsITimelineService exists so that JavaScript code
  75  * can mark the timeline.
  76  */
  77 [scriptable, uuid(93276790-3daf-11d5-b67d-000064657374)]
  78 interface nsITimelineService : nsISupports
  79 {
  80     /**
  81      * mark()
  82      * Print "<elapsed time>: <text>\n" in the timeline log file.
  83      */
  84     void mark(in string text);
  85
  86     /**
  87      * causes subsequent marks to be indented for a more readable
  88      * report.
  89      */
  90     void indent();
  91
  92     /**
  93      * Causes subsequent marks to be outdented.
  94      */
  95     void outdent();
  96
  97     /**
  98      * enter/leave bracket code with "<text>..." and "...<text>" as
  99      * well as indentation.
 100      */
 101     void enter(in string text);
 102     void leave(in string text);
 103
 104     void startTimer(in string timerName);
 105
 106     void stopTimer(in string timerName);
 107
 108     void markTimer(in string timerName);
 109
 110     void resetTimer(in string timerName);
 111
 112     // Mark a timer, plus an additional comment
 113     void markTimerWithComment(in string timerName, in string comment);
 114 };
 115
 116 %{C++
 117 #endif /* MOZ_TIMELINE */
 118 %}
 119
 120
 121 %{C++
 122
 123 #ifdef MOZ_TIMELINE
 124
 125 /*
 126  * These are equivalent to the corresponding nsITimelineService
 127  * methods, and can be called before XPCOM is initialized.
 128  */
 129 extern "C" NS_COM nsresult NS_TimelineMark(const char *text, ...);
 130 extern "C" NS_COM nsresult NS_TimelineForceMark(const char *text, ...);
 131 extern "C" NS_COM nsresult NS_TimelineStartTimer(const char *timerName);
 132 extern "C" NS_COM nsresult NS_TimelineStopTimer(const char *timerName);
 133 extern "C" NS_COM nsresult NS_TimelineResetTimer(const char *timerName);
 134 extern "C" NS_COM nsresult NS_TimelineMarkTimer(const char *timerName, const char *str=nsnull);
 135 extern "C" NS_COM nsresult NS_TimelineIndent();
 136 extern "C" NS_COM nsresult NS_TimelineOutdent();
 137 extern "C" NS_COM nsresult NS_TimelineEnter(const char *text);
 138 extern "C" NS_COM nsresult NS_TimelineLeave(const char *text);
 139
 140 /*
 141  * Use these macros for the above calls so we can easily compile them
 142  * out.
 143  */
 144 #define NS_TIMELINE_MARK(text) NS_TimelineMark(text)
 145 #define NS_TIMELINE_MARKV(args) NS_TimelineMark args
 146 #define NS_TIMELINE_INDENT() NS_TimelineIndent()
 147 #define NS_TIMELINE_OUTDENT() NS_TimelineOutdent()
 148 #define NS_TIMELINE_ENTER(text) NS_TimelineEnter(text)
 149 #define NS_TIMELINE_LEAVE(text) NS_TimelineLeave(text)
 150 #define NS_TIMELINE_START_TIMER(timerName) NS_TimelineStartTimer(timerName)
 151 #define NS_TIMELINE_STOP_TIMER(timerName) NS_TimelineStopTimer(timerName)
 152 #define NS_TIMELINE_MARK_TIMER(timerName) NS_TimelineMarkTimer(timerName)
 153 #define NS_TIMELINE_RESET_TIMER(timerName) NS_TimelineResetTimer(timerName)
 154 #define NS_TIMELINE_MARK_TIMER1(timerName, str) NS_TimelineMarkTimer(timerName, str)
 155
 156 /*
 157  * Helper class to time functions. Use only static strings.
 158  */
 159 class nsFunctionTimer {
 160 public:
 161     const char *mTimer;
 162     PRBool mMark;
 163     const char *mMarkStr;
 164     nsFunctionTimer(const char *timer, PRBool mark = PR_TRUE, const char *markStr = nsnull)
 165         : mTimer(timer), mMark(mark), mMarkStr(markStr)
 166     {
 167         NS_TIMELINE_START_TIMER(mTimer);
 168     }
 169
 170     ~nsFunctionTimer()
 171     {
 172         NS_TIMELINE_STOP_TIMER(mTimer);
 173         if (mMark)
 174             if (mMarkStr)
 175                 NS_TIMELINE_MARK_TIMER1(mTimer, mMarkStr);
 176             else
 177                 NS_TIMELINE_MARK_TIMER(mTimer);
 178     }
 179 };
 180
 181 /*
 182  * NS_TIMELINE_MARK_ macros for various data types.  Each of these
 183  * macros replaces "%s" in its "text" argument with a string
 184  * representation of its last argument.
 185  *
 186  * Please feel free to add more NS_TIMELINE_MARK_ macros for
 187  * various data types so that code using NS_TIMELINE is uncluttered.
 188  * Don't forget the empty versions in the #else section below for
 189  * non-timeline builds.
 190  */
 191 #define NS_TIMELINE_MARK_URI(text, uri) \
 192     { \
 193         nsCAutoString spec; \
 194         if (uri) { \
 195             uri->GetSpec(spec); \
 196         } \
 197         if (!spec.IsEmpty()) { \
 198             NS_TimelineMark(text, spec.get()); \
 199         } else { \
 200             NS_TimelineMark(text, "??"); \
 201         } \
 202     }
 203
 204 #define NS_TIMELINE_MARK_CHANNEL(text, channel) \
 205     { \
 206         nsCOMPtr<nsIURI> uri; \
 207         if (channel) { \
 208             channel->GetURI(getter_AddRefs(uri)); \
 209         } \
 210         NS_TIMELINE_MARK_URI(text, uri); \
 211     }
 212
 213 #define NS_TIMELINE_MARK_LOADER(text, loader) \
 214     { \
 215         nsCOMPtr<nsIRequest> request; \
 216         loader->GetRequest(getter_AddRefs(request)); \
 217         nsCOMPtr<nsIChannel> channel(do_QueryInterface(request)); \
 218         NS_TIMELINE_MARK_CHANNEL(text, channel); \
 219     }
 220 #define NS_TIMELINE_MARK_FUNCTION(timer) nsFunctionTimer functionTimer(timer)
 221 #define NS_TIMELINE_MARK_FUNCTION1(timer, str) nsFunctionTimer functionTimer(timer, PR_TRUE, str)
 222 #define NS_TIMELINE_TIME_FUNCTION(timer) nsFunctionTimer functionTimer(timer, PR_FALSE) /* no mark, only time */
 223
 224 #else /* !defined(MOZ_TIMELINE) */
 225 #define NS_TIMELINE_MARK(text)
 226 #define NS_TIMELINE_MARKV(args)
 227 #define NS_TIMELINE_INDENT()
 228 #define NS_TIMELINE_OUTDENT()
 229 #define NS_TIMELINE_START_TIMER(timerName)
 230 #define NS_TIMELINE_STOP_TIMER(timerName)
 231 #define NS_TIMELINE_MARK_TIMER(timerName)
 232 #define NS_TIMELINE_RESET_TIMER(timerName)
 233 #define NS_TIMELINE_MARK_TIMER1(timerName, str)
 234 #define NS_TIMELINE_ENTER(text)
 235 #define NS_TIMELINE_LEAVE(text)
 236 #define NS_TIMELINE_MARK_URI(text, uri)
 237 #define NS_TIMELINE_MARK_FUNCTION(timer)
 238 #define NS_TIMELINE_TIME_FUNCTION(timer)
 239 #define NS_TIMELINE_MARK_CHANNEL(text, channel)
 240 #define NS_TIMELINE_MARK_LOADER(text, loader);
 241 #endif /* defined(MOZ_TIMELINE) */
 242 %}