MProfiler Class Reference

#include <MProfiler.h>

Class Description

Class for working with Maya's profiler.

MProfiler is a static class which provides access to Maya's profiler. Maya's profiler is used to profile execution time of instrumented code. User can review the profiling result in the Profiler Window. Or use the MEL command "profiler" to save the profiling result to a file.

The profiling results are represented by two types of events: Normal Event and Signal Event. Normal Event has a duration representing the execution time of the instrumented code. A Signal Event only remembers the start moment and has no knowledge about duration. It can be used in cases when the user does not care about the duration but only cares if this event does happen.

This class provides access to profiler settings and the profiling result. To instrument a specific code snippet you must create an instance of MProfilerScope. See that class for more details.

This class does not provide the ability to start/stop the recording. Recording can be started/stopped using either the Profiler Window or the "profiler -sampling true/false" command. When recording is active only those categories which have been set to be recorded (i.e. categoryRecording(categoryId) returns true) will have their profiling data included in the recording.

There are two ways to instrument code, one is to use MProfiler::eventBegin and MProfier::eventEnd, which give user more flexible control over when to start and stop the profiling for certain part of code, but it is also the user's responsibility to call eventEnd for eventBegin, if user fails to do so, the event will be taken as a signal event. The other way is to use MProfilingScope, which will stop the event automatically when the MProfilingScope object is out of its life scope.

Public Types
enum	ProfilingColor
	Colors for different profiling categories in Profiler Window.

Static Public Member Functions
static int	addCategory (const char *categoryName)
	Add a new profiling category. More...
static int	removeCategory (const char *categoryName)
	Remove an existing profiling category. More...
static void	getAllCategories (MStringArray &categoryNames)
	Return an array of the existing category names. More...
static int	getCategoryIndex (const char *categoryName)
	Returns the category index. More...
static const char *	getCategoryName (int categoryId)
	Returns the category name. More...
static bool	categoryRecording (const char *categoryName)
	Determine if a given category is allowed to be recorded. More...
static bool	categoryRecording (int categoryId)
	Determine if a given category is allowed to be recorded. More...
static void	setCategoryRecording (const char *categoryName, bool active)
	Enable or disable the recording of the given category. More...
static void	setCategoryRecording (int categoryId, bool active)
	Enable or disable the recording of the given category. More...
static void	signalEvent (int categoryId, ProfilingColor colorIndex, const char *eventName, const char *description=NULL)
	Sending out a profiling signal. More...
static int	eventBegin (int categoryId, ProfilingColor colorIndex, const char *eventName, const char *description=NULL)
	Start a profiling event. More...
static void	eventEnd (int eventId)
	Stop a profiling event. More...
static int	getEventCount ()
	Returns the events count. More...
static MUint64	getEventTime (int eventIndex)
	Returns the time the event happens in microseconds. More...
static int	getEventDuration (int eventIndex)
	Returns the duration of the event in microseconds. More...
static const char *	getEventName (int eventIndex)
	Returns the name of the specified event. More...
static const char *	getDescription (int eventIndex)
	Returns the event description. More...
static int	getEventCategory (int eventIndex)
	Returns the category the event belongs to. More...
static int	getThreadId (int eventIndex)
	Returns the thread id the event ran on. More...
static int	getCPUId (int eventIndex)
	Returns the CPU id the event ran on. More...
static bool	isSignalEvent (int eventIndex)
	Determine if a given event is a Signal Event. More...
static MProfiler::ProfilingColor	getColor (int eventIndex)
	Returns the color used to draw this event in the Profiler Window. More...
static int	getThreadDuration (int eventIndex)
	Returns the duration of the thread for a given event in microseconds. More...
static int	getBufferSize ()
	Returns the profiling buffer size. More...
static MStatus	setBufferSize (int sizeInMegaytes)
	Set the new profiling buffer size. More...
static bool	recordingActive ()
	Determine if recording is active. More...
static bool	eventDataAvailable ()
	Determine if any recorded event data is available. More...
static bool	resetRecording ()
	Clear out any recorded data. More...
static void	setRecordingActive (bool val)
	Enable or disable recording. More...
static bool	saveRecording (const MString &fileName)
	Save recording to a specified file location. More...
static bool	loadRecording (const MString &fileName)
	Load a recording from a specified file location. More...
static bool	isDataFromFile ()
	Return if the current event data was loaded from file. More...
static int	getNumberOfCPUs ()
	Return the number of CPUS used for profiling. More...
static const char *	className ()
	Returns the name of this class. More...

Member Function Documentation

int addCategory ( const char *  categoryName )

static

Add a new profiling category.

Categories can only be added when sampling is off and the buffer is empty.

Parameters

[in]

categoryName

The name of the category to add.

Returns

Index of the newly added category or -1 if fail to add the category.

Examples:

int removeCategory ( const char *  categoryName )

static

Remove an existing profiling category.

User can only remove category when the sampling is off and the buffer is empty.

Parameters

[in]

categoryName

The name of the category to remove.

Returns

Index of the removed category or -1 if fail to remove the category..

void getAllCategories ( MStringArray &  categoryNames )

static

Return an array of the existing category names.

Parameters

[out]

categoryNames

The names of all the existing categories.

int getCategoryIndex ( const char *  categoryName )

static

Returns the category index.

Parameters

[in]

categoryName

Name of the category to query.

Returns

The index of the specified category. -1 if no category with this name.

const char * getCategoryName ( int  categoryId )

static

Returns the category name.

Parameters

[in]

categoryId

Index of the category to query.

Returns

The name of the specified category.

bool categoryRecording ( const char *  categoryName )

static

Determine if a given category is allowed to be recorded.

Parameters

[in]

categoryName

Name of the category to query.

Returns

True if the specified category is currently being recorded, otherwise false.

bool categoryRecording ( int  categoryId )

static

Determine if a given category is allowed to be recorded.

Parameters

[in]

categoryId

Index of the category to query.

Returns

True if the specified category is currently being recorded, otherwise false.

void setCategoryRecording ( const char *  categoryName, bool  active  )

static

Enable or disable the recording of the given category.

Parameters

[in]	categoryName	Name of the category to set.
[in]	active	If True, the category will be recorded when profiling starts. If False, the category will not be recorded when profiling starts.

void setCategoryRecording ( int  categoryId, bool  active  )

static

Enable or disable the recording of the given category.

Parameters

[in]	categoryId	The category to set.
[in]	active	If True, the category will be recorded when profiling starts. If False, the category will not be recorded when profiling starts.

void signalEvent ( int  categoryId, ProfilingColor  colorIndex, const char *  eventName, const char *  description = NULL  )

static

Sending out a profiling signal.

Parameters

[in]	categoryId	The index of the category which the event belongs to.
[in]	colorIndex	The color to draw the profiling result in Profiler Window.
[in]	eventName	The name of the event.
[in]	description	Description of the event.

int eventBegin ( int  categoryId, ProfilingColor  colorIndex, const char *  eventName, const char *  description = NULL  )

static

Start a profiling event.

Parameters

[in]	categoryId	The index of the category which the event belongs to.
[in]	colorIndex	The color to draw the profiling result in Profiler Window.
[in]	eventName	The name of the event.
[in]	description	Description of the event.

Returns

The index of the started event.

void eventEnd ( int  eventId )

static

Stop a profiling event.

Parameters

[in]

eventId

The index of the event to stop.

int getEventCount ( )

static

Returns the events count.

Returns

The number of events in the profiling buffer.

MUint64 getEventTime ( int  eventIndex )

static

Returns the time the event happens in microseconds.

If you need to convert this time to other time unit, please create a MTime(microseconds/1000, kMilliSeconds) then do all time conversions by MTime.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The time the event happens in microseconds.

int getEventDuration ( int  eventIndex )

static

Returns the duration of the event in microseconds.

Note that a signal event has a 0 duration. If you need to convert this time to other time unit, please create a MTime(microseconds/1000, kMilliSeconds) then do all time conversions by MTime.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The duration of the event in microseconds.

const char * getEventName ( int  eventIndex )

static

Returns the name of the specified event.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The name of the specified event.

const char * getDescription ( int  eventIndex )

static

Returns the event description.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The event description.

int getEventCategory ( int  eventIndex )

static

Returns the category the event belongs to.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The category the event belongs to.

int getThreadId ( int  eventIndex )

static

Returns the thread id the event ran on.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The thread id the event ran on.

int getCPUId ( int  eventIndex )

static

Returns the CPU id the event ran on.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The CPU id the event ran on.

bool isSignalEvent ( int  eventIndex )

static

Determine if a given event is a Signal Event.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

True if the event is a Single Event, false otherwise.

MProfiler::ProfilingColor getColor ( int  eventIndex )

static

Returns the color used to draw this event in the Profiler Window.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The color used to draw this event in the Profiler Window.

int getThreadDuration ( int  eventIndex )

static

Returns the duration of the thread for a given event in microseconds.

Parameters

[in]

eventIndex

The index of the event in the profiling buffer.

Returns

The duration of the thread in microseconds.

int getBufferSize ( )

static

Returns the profiling buffer size.

Returns

The profiling buffer size in megabytes.

MStatus setBufferSize ( int  sizeInMegaytes )

static

Set the new profiling buffer size.

The new buffer size will take effect for next recording. Before next recording started, the events already in the buffer won't be affected.

Parameters

[in]

sizeInMegaytes

The new profiling buffer size in megabytes.

Returns

• MS::kSuccess operation successful
• MS::kFailure operation failed

bool recordingActive ( )

static

Determine if recording is active.

Returns

True if recording is active

bool eventDataAvailable ( )

static

Determine if any recorded event data is available.

Returns

True if data is available

bool resetRecording ( )

static

Clear out any recorded data.

If a recording is active (samplingActive() returns True) then the data will not be cleared.

Returns

True if data was cleared

void setRecordingActive ( bool  val )

static

Enable or disable recording.

Parameters

[in]

val

Value for enabling

bool saveRecording ( const MString &  fileName )

static

Save recording to a specified file location.

Parameters

[in]

fileName

File location to save to.

Returns

True if recording was saved.

bool loadRecording ( const MString &  fileName )

static

Load a recording from a specified file location.

Parameters

[in]

fileName

File location to load from.

Returns

True if recording was loaded.

bool isDataFromFile ( )

static

Return if the current event data was loaded from file.

Returns

True if event data was loaded from file.

int getNumberOfCPUs ( )

static

Return the number of CPUS used for profiling.

If the current event data is loaded from file (isDataFromFile() returns True) then the number from the loaded data will be returned.

Returns

Number of CPUs.

const char * className ( )

static

Returns the name of this class.

Returns

The name of this class.

---

The documentation for this class was generated from the following files:

• MProfiler.h
• MProfiler.cpp