win/idl/nsITimelineService.idl - chromium/deps/xulrunner-sdk - Git at Google

 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 /* ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
  * The contents of this file are subject to the Mozilla 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/MPL/
  *
  * 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 the Initial Developer are Copyright (C) 1998
  * the Initial Developer. All Rights Reserved.
  *
  * Contributor(s):
  *
  * Alternatively, the contents of this file may be used under the terms of
  * either of the GNU General Public License Version 2 or later (the "GPL"),
  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  * in which case the provisions of the GPL or the LGPL are applicable instead
  * of those above. If you wish to allow use of your version of this file only
  * under the terms of either the GPL or the LGPL, and not to allow others to
  * use your version of this file under the terms of the MPL, indicate your
  * decision by deleting the provisions above and replace them with the notice
  * and other provisions required by the GPL or the LGPL. If you do not delete
  * the provisions above, a recipient may use your version of this file under
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */

 #include "nsISupports.idl"

 %{C++
 #ifdef MOZ_TIMELINE
 %}

 /**
  * nsITimelineService is used to construct 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);

     void resetTimer(in string timerName);

     // Mark a timer, plus an additional comment
     void markTimerWithComment(in string timerName, in string comment);
 };

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


 %{C++

 #ifdef MOZ_TIMELINE

 /*
  * These are equivalent to the corresponding nsITimelineService
  * methods, and can be called before XPCOM is initialized.
  */
 extern "C" NS_COM nsresult NS_TimelineMark(const char *text, ...);
 extern "C" NS_COM nsresult NS_TimelineForceMark(const char *text, ...);
 extern "C" NS_COM nsresult NS_TimelineStartTimer(const char *timerName);
 extern "C" NS_COM nsresult NS_TimelineStopTimer(const char *timerName);
 extern "C" NS_COM nsresult NS_TimelineResetTimer(const char *timerName);
 extern "C" NS_COM nsresult NS_TimelineMarkTimer(const char *timerName, const char *str=nsnull);
 extern "C" NS_COM nsresult NS_TimelineIndent();
 extern "C" NS_COM nsresult NS_TimelineOutdent();
 extern "C" NS_COM nsresult NS_TimelineEnter(const char *text);
 extern "C" NS_COM 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)
 #define NS_TIMELINE_RESET_TIMER(timerName) NS_TimelineResetTimer(timerName)
 #define NS_TIMELINE_MARK_TIMER1(timerName, str) NS_TimelineMarkTimer(timerName, str)

 /*
  * Helper class to time functions. Use only static strings.
  */
 class nsFunctionTimer {
 public:
     const char *mTimer;
     PRBool mMark;
     const char *mMarkStr;
     nsFunctionTimer(const char *timer, PRBool mark = PR_TRUE, const char *markStr = nsnull)
         : mTimer(timer), mMark(mark), mMarkStr(markStr)
     {
         NS_TIMELINE_START_TIMER(mTimer);
     }

     ~nsFunctionTimer()
     {
         NS_TIMELINE_STOP_TIMER(mTimer);
         if (mMark)
             if (mMarkStr)
                 NS_TIMELINE_MARK_TIMER1(mTimer, mMarkStr);
             else
                 NS_TIMELINE_MARK_TIMER(mTimer);
     }
 };

 /*
  * 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) \
     { \
         nsCAutoString spec; \
         if (uri) { \
             uri->GetSpec(spec); \
         } \
         if (!spec.IsEmpty()) { \
             NS_TimelineMark(text, spec.get()); \
         } 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); \
     }
 #define NS_TIMELINE_MARK_FUNCTION(timer) nsFunctionTimer functionTimer(timer)
 #define NS_TIMELINE_MARK_FUNCTION1(timer, str) nsFunctionTimer functionTimer(timer, PR_TRUE, str)
 #define NS_TIMELINE_TIME_FUNCTION(timer) nsFunctionTimer functionTimer(timer, PR_FALSE) /* no mark, only time */

 #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_RESET_TIMER(timerName)
 #define NS_TIMELINE_MARK_TIMER1(timerName, str)
 #define NS_TIMELINE_ENTER(text)
 #define NS_TIMELINE_LEAVE(text)
 #define NS_TIMELINE_MARK_URI(text, uri)
 #define NS_TIMELINE_MARK_FUNCTION(timer)
 #define NS_TIMELINE_TIME_FUNCTION(timer)
 #define NS_TIMELINE_MARK_CHANNEL(text, channel)
 #define NS_TIMELINE_MARK_LOADER(text, loader);
 #endif /* defined(MOZ_TIMELINE) */
 %}
	/* -- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -- */
	/* *** BEGIN LICENSE BLOCK ***
	* Version: MPL 1.1/GPL 2.0/LGPL 2.1
	*
	* The contents of this file are subject to the Mozilla 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/MPL/
	*
	* 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 the Initial Developer are Copyright (C) 1998
	* the Initial Developer. All Rights Reserved.
	*
	* Contributor(s):
	*
	* Alternatively, the contents of this file may be used under the terms of
	* either of the GNU General Public License Version 2 or later (the "GPL"),
	* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
	* in which case the provisions of the GPL or the LGPL are applicable instead
	* of those above. If you wish to allow use of your version of this file only
	* under the terms of either the GPL or the LGPL, and not to allow others to
	* use your version of this file under the terms of the MPL, indicate your
	* decision by deleting the provisions above and replace them with the notice
	* and other provisions required by the GPL or the LGPL. If you do not delete
	* the provisions above, a recipient may use your version of this file under
	* the terms of any one of the MPL, the GPL or the LGPL.
	*
	* *** END LICENSE BLOCK *** */

	#include "nsISupports.idl"

	%{C++
	#ifdef MOZ_TIMELINE
	%}

	/**
	* nsITimelineService is used to construct 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);

	void resetTimer(in string timerName);

	// Mark a timer, plus an additional comment
	void markTimerWithComment(in string timerName, in string comment);
	};

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


	%{C++

	#ifdef MOZ_TIMELINE

	/*
	* These are equivalent to the corresponding nsITimelineService
	* methods, and can be called before XPCOM is initialized.
	*/
	extern "C" NS_COM nsresult NS_TimelineMark(const char *text, ...);
	extern "C" NS_COM nsresult NS_TimelineForceMark(const char *text, ...);
	extern "C" NS_COM nsresult NS_TimelineStartTimer(const char *timerName);
	extern "C" NS_COM nsresult NS_TimelineStopTimer(const char *timerName);
	extern "C" NS_COM nsresult NS_TimelineResetTimer(const char *timerName);
	extern "C" NS_COM nsresult NS_TimelineMarkTimer(const char timerName, const char str=nsnull);
	extern "C" NS_COM nsresult NS_TimelineIndent();
	extern "C" NS_COM nsresult NS_TimelineOutdent();
	extern "C" NS_COM nsresult NS_TimelineEnter(const char *text);
	extern "C" NS_COM 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)
	#define NS_TIMELINE_RESET_TIMER(timerName) NS_TimelineResetTimer(timerName)
	#define NS_TIMELINE_MARK_TIMER1(timerName, str) NS_TimelineMarkTimer(timerName, str)

	/*
	* Helper class to time functions. Use only static strings.
	*/
	class nsFunctionTimer {
	public:
	const char *mTimer;
	PRBool mMark;
	const char *mMarkStr;
	nsFunctionTimer(const char timer, PRBool mark = PR_TRUE, const char markStr = nsnull)
	: mTimer(timer), mMark(mark), mMarkStr(markStr)
	{
	NS_TIMELINE_START_TIMER(mTimer);
	}

	~nsFunctionTimer()
	{
	NS_TIMELINE_STOP_TIMER(mTimer);
	if (mMark)
	if (mMarkStr)
	NS_TIMELINE_MARK_TIMER1(mTimer, mMarkStr);
	else
	NS_TIMELINE_MARK_TIMER(mTimer);
	}
	};

	/*
	* 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) \
	{ \
	nsCAutoString spec; \
	if (uri) { \
	uri->GetSpec(spec); \
	} \
	if (!spec.IsEmpty()) { \
	NS_TimelineMark(text, spec.get()); \
	} 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); \
	}
	#define NS_TIMELINE_MARK_FUNCTION(timer) nsFunctionTimer functionTimer(timer)
	#define NS_TIMELINE_MARK_FUNCTION1(timer, str) nsFunctionTimer functionTimer(timer, PR_TRUE, str)
	#define NS_TIMELINE_TIME_FUNCTION(timer) nsFunctionTimer functionTimer(timer, PR_FALSE) /* no mark, only time */

	#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_RESET_TIMER(timerName)
	#define NS_TIMELINE_MARK_TIMER1(timerName, str)
	#define NS_TIMELINE_ENTER(text)
	#define NS_TIMELINE_LEAVE(text)
	#define NS_TIMELINE_MARK_URI(text, uri)
	#define NS_TIMELINE_MARK_FUNCTION(timer)
	#define NS_TIMELINE_TIME_FUNCTION(timer)
	#define NS_TIMELINE_MARK_CHANNEL(text, channel)
	#define NS_TIMELINE_MARK_LOADER(text, loader);
	#endif /* defined(MOZ_TIMELINE) */
	%}