Namespace: SC.Benchmark

This bit of meta-programming magic can install a benchmark handler on any object method. When a benchmark is installed, the time required to execute the method will be printed to the console log every time the method is called.

This class can be used to implement benchmarking. To use this object, just call start() with a key name and end() with a keyname. The benchmark will be logged. If you set verbose = true, then benchmark will log every time it saves a bench. Otherwise, it just keeps stats. You can get the stats by calling report().

Benchmark does not require anything other than the date.js class. It also does not rely on SC.Object so that you can benchmark code in that area as well.

The benchmark has three types of reports.

report(): Returns an abbreviated list with just the durations of the bench. Also, it averages multiple runs. Everything is reported on the top level only.
timelineReport(): Returns an list of benchmarks and sub-benchmarks. If the the globalStartTime is set, then it will show relative time from that time.
timelineChart(): Displays a chart of all the benchmarks (not sub-benchmarks) relative to the first time capture or to the globalStartTime. Hide this by calling hideChart()

Defined in: benchmark.js

Since:: SproutCore 1.0

Field Summary

SC.Benchmark.enabled
SC.Benchmark.events
SC.Benchmark.globalStartTime
SC.Benchmark.stats
SC.Benchmark.verbose

Class Methods

Field Detail

SC.Benchmark.enabled Boolean

If false, benchmarking will be disabled. You might want to disable this during production to maximize performance.

Default value:: YES

SC.Benchmark.events Object

Events are a way of assigning specific, individual times to names, rather than durations of time. A benchmark event can only occur once—if it occurs again, it will overwrite the old event.

The purpose of events is different than the purpose for normal benchmarks. Normal benchmarks may be used to benchmark a specific process, and may do so repeatedly; events, conversely, are usually used to benchmark things like startup time, and occur only once. For instance, an 'event' is registered when the document is ready.

Events are kept as a hash of names to timestamps. To add an event, just set it:

SC.Benchmark.events['myEventName'] = new Date().getTime();

// Or, more conveniently:
SC.Benchmark.addEvent('myEventName', [optional time]);

On a timeline chart, events are usually represented as lines rather than bars. However, if you add eventNameStart and eventNameEnd, they will be automatically added as standard benchmarks.

This is useful when adding preload events to SC.benchmarkPreloadEvents; as SC.Benchmark does not yet exist, you cannot call .start() and .end(), but adding the items to SC.benchmarkPreloadEvents will ensure they are included.

SC.Benchmark.globalStartTime Number

If set, one can tell when the benchmark is started relatively to the global start time.

This property is set to a default automatically (from HTML5 NavigationTiming if possible, otherwise the SC bootstrap).

Default value:: null

SC.Benchmark.stats Object

This hash stores collected stats. It contains key value pairs. The value will be a hash with the following properties:

runs: the number of times this stat has run
amt: the total time consumed by this (divide by runs to get avg)
name: an optional longer name you assigned to the stat key. Set this using name().

SC.Benchmark.verbose Boolean

If true, then benchmarks will be logged to the console as they are recorded.

Default value:: NO

Class Method Detail

addEvent(name, time)

Adds an 'event' to the events hash.

Unlike normal benchmarks, recorded with start/end and that represent a block of time, events represent a single instance in time. Further, unlike normal benchmarks, which may be run more than once for the same benchmark name, only one instance in time will be recorded for any event name.

Parameters:
name String: A name that identifies the event. If addEvent is called again with the same name, the previous call's timestamp will be overwritten.
time Number: Optional. The timestamp to record for the event.

bench(func, key, reps)

This is a simple way to benchmark a function. The function will be run with the name you provide the number of times you indicate. Only the function is a required param.

Parameters:
func Function: function to benchmark
key String Optional: benchmark key
reps Number Optional: how many times to run the function
Returns:
*: Most recent return value from func

end(key, parentKey, time)

Call this method at the end of whatever you want to collect. This will save the collected benchmark.

Parameters:
key String: The benchmark key you used when you called start()
parentKey String: The benchmark parent key you used when you called start()
time Number: Only pass if you want to explicitly set the end time. Otherwise start time is now.

endProfile(key)

Parameters:
key

getTimelineChartContent()

Returns a hash containing the HTML representing the timeline chart, and various metrics and information about the chart:

- html
- totalWidth
- totalHeight
- totalCapturedTime
- pointsCaptured

Returns:
Hash

getTimelineChartView()

Returns a view with the timeline chart. The view has a 'reload' method to refresh its data.

Returns:
SC.View

hideChart()

install(object, method, topLevelOnly)

Install a wrapper around a method to benchmark it whenever it is run.

Parameters:
object Object: target object to install on
method String: name of the method on object
topLevelOnly Boolean: should recursive calls to this method with the same key will be ignored

log(key)

This method is just like report() except that it will log the results to the console.

Parameters:
key

report(key)

This method will return a string containing a report of the stats collected so far. If you pass a key, only the stats for that key will be returned. Otherwise, all keys will be used.

Parameters:
key

restore(object, method)

Restore the original method, deactivating the benchmark.

Parameters:
object Object: the object to change
method String: the method name as a string

setGlobalStartTime(time)

Set the inital global start time.

Parameters:
time Number: global start time

start(key, parentKey, time, topLevelOnly)

Call this method at the start of whatever you want to collect. If a parentKey is passed, then you will attach the stat to the parent, otherwise it will be on the top level. If topLevelOnly is passed, then recursive calls to the start will be ignored and only the top level call will be benchmarked.

Parameters:
key String: A unique key that identifies this benchmark. All calls to start/end with the same key will be groups together.
parentKey String: A unique key that identifies the parent benchmark. All calls to start/end with the same key will be groups together.
time Number: Only pass if you want to explicitly set the start time. Otherwise the start time is now.
topLevelOnly Boolean: If true then recursive calls to this method with the same key will be ignored.
Returns:
String: the passed key

startProfile(key)

This will activate profiling if you have Firebug installed. Otherwise does nothing.

Parameters:
key

timelineChart(appName)

Generate a human readable benchmark chart. Pass in appName if you desire.

Parameters:
appName

timelineReport(application)

Generate a human readable benchmark report. Pass in appName if you desire.

Parameters:
application String: name.

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)