File Manager
Viewing File: Profile.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class RubyProf::Profile - ruby-prof</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
</script>
<script src="../js/jquery.js"></script>
<script src="../js/darkfish.js"></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link">Object
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-c-profile">::profile</a>
<li ><a href="#method-i-eliminate_methods-21">#eliminate_methods!</a>
<li ><a href="#method-i-pause">#pause</a>
<li ><a href="#method-i-paused-3F">#paused?</a>
<li ><a href="#method-i-post_process">#post_process</a>
<li ><a href="#method-i-resume">#resume</a>
<li ><a href="#method-i-running-3F">#running?</a>
<li ><a href="#method-i-start">#start</a>
<li ><a href="#method-i-stop">#stop</a>
<li ><a href="#method-i-threads">#threads</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-RubyProf::Profile">
<h1 id="class-RubyProf::Profile" class="class">
class RubyProf::Profile
</h1>
<section class="description">
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
new()
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
new(options)
</span>
</div>
<div class="method-description">
<p>Returns a new profiler. Possible options for the options hash are:</p>
<dl class="rdoc-list note-list"><dt>measure_mode
<dd>
<p>Measure mode. Specifies the profile measure mode. If not specified,
defaults to RubyProf::WALL_TIME.</p>
</dd><dt>exclude_threads
<dd>
<p>Threads to exclude from the profiling results.</p>
</dd><dt>include_threads
<dd>
<p>Focus profiling on only the given threads. This will ignore all other
threads.</p>
</dd><dt>merge_fibers
<dd>
<p>Whether to merge all fibers under a given thread. This should be used when
profiling for a callgrind printer.</p>
</dd></dl>
<div class="method-source-code" id="new-source">
<pre>static VALUE
prof_initialize(int argc, VALUE *argv, VALUE self)
{
prof_profile_t* profile = prof_get_profile(self);
VALUE mode_or_options;
VALUE mode = Qnil;
VALUE exclude_threads = Qnil;
VALUE include_threads = Qnil;
VALUE merge_fibers = Qnil;
int i;
switch (rb_scan_args(argc, argv, "02", &mode_or_options, &exclude_threads)) {
case 0:
break;
case 1:
if (FIXNUM_P(mode_or_options)) {
mode = mode_or_options;
}
else {
Check_Type(mode_or_options, T_HASH);
mode = rb_hash_aref(mode_or_options, ID2SYM(rb_intern("measure_mode")));
merge_fibers = rb_hash_aref(mode_or_options, ID2SYM(rb_intern("merge_fibers")));
exclude_threads = rb_hash_aref(mode_or_options, ID2SYM(rb_intern("exclude_threads")));
include_threads = rb_hash_aref(mode_or_options, ID2SYM(rb_intern("include_threads")));
}
break;
case 2:
Check_Type(exclude_threads, T_ARRAY);
break;
}
if (mode == Qnil) {
mode = INT2NUM(MEASURE_WALL_TIME);
} else {
Check_Type(mode, T_FIXNUM);
}
profile->measurer = prof_get_measurer(NUM2INT(mode));
profile->merge_fibers = merge_fibers != Qnil && merge_fibers != Qfalse;
if (exclude_threads != Qnil) {
Check_Type(exclude_threads, T_ARRAY);
assert(profile->exclude_threads_tbl == NULL);
profile->exclude_threads_tbl = threads_table_create();
for (i = 0; i < RARRAY_LEN(exclude_threads); i++) {
VALUE thread = rb_ary_entry(exclude_threads, i);
VALUE thread_id = rb_obj_id(thread);
st_insert(profile->exclude_threads_tbl, thread_id, Qtrue);
}
}
if (include_threads != Qnil) {
Check_Type(include_threads, T_ARRAY);
assert(profile->include_threads_tbl == NULL);
profile->include_threads_tbl = threads_table_create();
for (i = 0; i < RARRAY_LEN(include_threads); i++) {
VALUE thread = rb_ary_entry(include_threads, i);
VALUE thread_id = rb_obj_id(thread);
st_insert(profile->include_threads_tbl, thread_id, Qtrue);
}
}
return self;
}</pre>
</div>
</div>
</div>
<div id="method-c-profile" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
profile(&block) → self
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
profile(options, &block) → self
</span>
</div>
<div class="method-description">
<p>Profiles the specified block and returns a <a
href="Profile.html">RubyProf::Profile</a> object. Arguments are passed to
<a href="Profile.html">Profile</a> initialize method.</p>
<div class="method-source-code" id="profile-source">
<pre>static VALUE
prof_profile(int argc, VALUE *argv, VALUE klass)
{
int result;
VALUE profile = rb_class_new_instance(argc, argv, cProfile);
if (!rb_block_given_p())
{
rb_raise(rb_eArgError, "A block must be provided to the profile method.");
}
prof_start(profile);
rb_protect(rb_yield, profile, &result);
return prof_stop(profile);
}</pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-eliminate_methods-21" class="method-detail ">
<div class="method-heading">
<span class="method-name">eliminate_methods!</span><span
class="method-args">(matchers)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>eliminate some calls from the graph by merging the information into
callers. matchers can be a list of strings or regular expressions or the
name of a file containing regexps.</p>
<div class="method-source-code" id="eliminate_methods-21-source">
<pre><span class="ruby-comment"># File lib/ruby-prof/profile.rb, line 15</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier">eliminate_methods!</span>(<span class="ruby-identifier">matchers</span>)
<span class="ruby-identifier">matchers</span> = <span class="ruby-identifier">read_regexps_from_file</span>(<span class="ruby-identifier">matchers</span>) <span class="ruby-keyword">if</span> <span class="ruby-identifier">matchers</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">String</span>)
<span class="ruby-identifier">eliminated</span> = []
<span class="ruby-identifier">threads</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">thread</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">matchers</span>.<span class="ruby-identifier">each</span>{ <span class="ruby-operator">|</span><span class="ruby-identifier">matcher</span><span class="ruby-operator">|</span> <span class="ruby-identifier">eliminated</span>.<span class="ruby-identifier">concat</span>(<span class="ruby-identifier">eliminate_methods</span>(<span class="ruby-identifier">thread</span>.<span class="ruby-identifier">methods</span>, <span class="ruby-identifier">matcher</span>)) }
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">eliminated</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-pause" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
pause → self
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Pauses collecting profile data.</p>
<div class="method-source-code" id="pause-source">
<pre>static VALUE
prof_pause(VALUE self)
{
prof_profile_t* profile = prof_get_profile(self);
if (profile->running == Qfalse)
{
rb_raise(rb_eRuntimeError, "RubyProf is not running.");
}
if (profile->paused == Qfalse)
{
profile->paused = Qtrue;
profile->measurement_at_pause_resume = profile->measurer->measure();
st_foreach(profile->threads_tbl, pause_thread, (st_data_t) profile);
}
return self;
}</pre>
</div>
</div>
</div>
<div id="method-i-paused-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
paused? → boolean
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns whether a profile is currently paused.</p>
<div class="method-source-code" id="paused-3F-source">
<pre>static VALUE
prof_paused(VALUE self)
{
prof_profile_t* profile = prof_get_profile(self);
return profile->paused;
}</pre>
</div>
</div>
</div>
<div id="method-i-post_process" class="method-detail ">
<div class="method-heading">
<span class="method-name">post_process</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>This method gets called once profiling has been completed but before
results are returned to the user. Thus it provides a hook to do any
necessary post-processing on the call graph.</p>
<div class="method-source-code" id="post_process-source">
<pre><span class="ruby-comment"># File lib/ruby-prof/profile.rb, line 7</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier">post_process</span>
<span class="ruby-keyword">self</span>.<span class="ruby-identifier">threads</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">thread</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">thread</span>.<span class="ruby-identifier">detect_recursion</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-resume" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
resume → self
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
resume(&block) → self
</span>
</div>
<div class="method-description">
<p>Resumes recording profile data.</p>
<div class="method-source-code" id="resume-source">
<pre>static VALUE
prof_resume(VALUE self)
{
prof_profile_t* profile = prof_get_profile(self);
if (profile->running == Qfalse)
{
rb_raise(rb_eRuntimeError, "RubyProf is not running.");
}
if (profile->paused == Qtrue)
{
profile->paused = Qfalse;
profile->measurement_at_pause_resume = profile->measurer->measure();
st_foreach(profile->threads_tbl, unpause_thread, (st_data_t) profile);
}
return rb_block_given_p() ? rb_ensure(rb_yield, self, prof_pause, self) : self;
}</pre>
</div>
</div>
</div>
<div id="method-i-running-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
running? → boolean
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns whether a profile is currently running.</p>
<div class="method-source-code" id="running-3F-source">
<pre>static VALUE
prof_running(VALUE self)
{
prof_profile_t* profile = prof_get_profile(self);
return profile->running;
}</pre>
</div>
</div>
</div>
<div id="method-i-start" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
start → self
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Starts recording profile data.</p>
<div class="method-source-code" id="start-source">
<pre>static VALUE
prof_start(VALUE self)
{
char* trace_file_name;
prof_profile_t* profile = prof_get_profile(self);
if (profile->running == Qtrue)
{
rb_raise(rb_eRuntimeError, "RubyProf.start was already called");
}
profile->running = Qtrue;
profile->paused = Qfalse;
profile->last_thread_data = NULL;
/* open trace file if environment wants it */
trace_file_name = getenv("RUBY_PROF_TRACE");
if (trace_file_name != NULL)
{
if (strcmp(trace_file_name, "stdout") == 0)
{
trace_file = stdout;
}
else if (strcmp(trace_file_name, "stderr") == 0)
{
trace_file = stderr;
}
else
{
trace_file = fopen(trace_file_name, "w");
}
}
prof_install_hook(self);
return self;
}</pre>
</div>
</div>
</div>
<div id="method-i-stop" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
stop → self
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Stops collecting profile data.</p>
<div class="method-source-code" id="stop-source">
<pre>static VALUE
prof_stop(VALUE self)
{
prof_profile_t* profile = prof_get_profile(self);
if (profile->running == Qfalse)
{
rb_raise(rb_eRuntimeError, "RubyProf.start was not yet called");
}
prof_remove_hook();
/* close trace file if open */
if (trace_file != NULL)
{
if (trace_file !=stderr && trace_file != stdout)
{
#ifdef _MSC_VER
_fcloseall();
#else
fclose(trace_file);
#endif
}
trace_file = NULL;
}
prof_pop_threads(profile);
/* Unset the last_thread_data (very important!)
and the threads table */
profile->running = profile->paused = Qfalse;
profile->last_thread_data = NULL;
/* Post process result */
rb_funcall(self, rb_intern("post_process") , 0);
return self;
}</pre>
</div>
</div>
</div>
<div id="method-i-threads" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
threads → array of RubyProf::Thread
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns an array of <a href="Thread.html">RubyProf::Thread</a> instances
that were executed while the the program was being run.</p>
<div class="method-source-code" id="threads-source">
<pre>static VALUE
prof_threads(VALUE self)
{
VALUE result = rb_ary_new();
prof_profile_t* profile = prof_get_profile(self);
st_foreach(profile->threads_tbl, collect_threads, result);
return result;
}</pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="http://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.2.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>