ruby-changes:31823
From: zzak <ko1@a...>
Date: Thu, 28 Nov 2013 21:44:44 +0900 (JST)
Subject: [ruby-changes:31823] zzak:r43902 (trunk): * doc/dtrace_probes.rdoc: [DOC] Import dtrace probes doc from wiki
zzak 2013-11-28 21:44:38 +0900 (Thu, 28 Nov 2013) New Revision: 43902 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=43902 Log: * doc/dtrace_probes.rdoc: [DOC] Import dtrace probes doc from wiki Added files: trunk/doc/dtrace_probes.rdoc Modified files: trunk/ChangeLog Index: doc/dtrace_probes.rdoc =================================================================== --- doc/dtrace_probes.rdoc (revision 0) +++ doc/dtrace_probes.rdoc (revision 43902) @@ -0,0 +1,172 @@ https://github.com/ruby/ruby/blob/trunk/doc/dtrace_probes.rdoc#L1 += DTrace Probes + +A list of DTrace probes and their functionality. "Module" and "Function" cannot +be defined in user defined probes (known as USDT), so they will not be +specified. Probe definitions are in the format of: + + provider:module:function:name(arguments) + +Since module and function cannot be specified, they will be blank. An example +probe definition for Ruby would then be: + + ruby:::function-entry(class name, method name, file name, line number) + +Where "ruby" is the provider name, module and function names are blank, the +probe name is "function-entry", and the probe takes four arguments: + +* class name +* method name +* file name +* line number + +== Probes List + +=== Stability + +Before we list the specific probes, let's talk about stability. Probe stability +is declared in the probes.d file at the bottom on the #pragma D attributes +lines. Here is a description of each of the stability declarations. + +[Provider name stability] + The provider name of "ruby" has been declared as stable. It is unlikely that + we will change the provider name from "ruby" to something else. + +[Module and Function stability] + Since we are not allowed to provide values for the module and function name, + the values we have provided (no value) is declared as stable. + +[Probe name stability] + The probe names are likely to change in the future, so they are marked as + "Evolving". Consumers should not depend on these names to be stable. + +[Probe argument stability] + The parameters passed to the probes are likely to change in the future, so + they are marked as "Evolving". Consumers should not depend on these to be + stable. + +=== Declared probes + +Probes are defined in the probes.d file. Here are the declared probes along +with when they are fired and the arguments they take: + +[ruby:::method-entry(classname, methodname, filename, lineno);] + This probe is fired just before a method is entered. + + classname name of the class (a string) + methodname name of the method about to be executed (a string) + filename the file name where the method is _being called_ (a string) + lineno the line number where the method is _being called_ (an int) + +[ruby:::method-return(classname, methodname, filename, lineno);] + This probe is fired just after a method has returned. The arguments are the + same as "ruby:::function-entry". + +[ruby:::cmethod-entry(classname, methodname, filename, lineno);] + This probe is fired just before a C method is entered. The arguments are the + same as "ruby:::function-entry". + +[ruby:::cmethod-return(classname, methodname, filename, lineno);] + This probe is fired just before a C method returns. The arguments are the + same as "ruby:::function-entry". + +[ruby:::require-entry(requiredfile, filename, lineno);] + This probe is fired on calls to rb_require_safe (when a file is required). + + requiredfile is the name of the file to be required (string). + filename is the file that called "require" (string). + lineno is the line number where the call to require was made (int). + +[ruby:::require-return(requiredfile, filename, lineno);] + This probe is fired just before rb_require_safe (when a file is required) + returns. The arguments are the same as "ruby:::require-entry". This probe + will not fire if there was an exception during file require. + +[ruby:::find-require-entry(requiredfile, filename, lineno);] + This probe is fired right before search_required is called. search_required + determines whether the file has already been required by searching loaded + features ($"), and if not, figures out which file must be loaded. + + requiredfile is the file to be required (string). + filename is the file that called "require" (string). + lineno is the line number where the call to require was made (int). + +[ruby:::find-require-return(requiredfile, filename, lineno);] + This probe is fired right after search_required returns. See the + documentation for "ruby:::find-require-entry" for more details. Arguments for + this probe are the same as "ruby:::find-require-entry". + +[ruby:::load-entry(loadedfile, filename, lineno);] + This probe is fired when calls to "load" are made. The arguments are the same + as "ruby:::require-entry". + +[ruby:::load-return(loadedfile, filename, lineno);] + This probe is fired when "load" returns. The arguments are the same as + "ruby:::load-entry". + +[ruby:::raise(classname, filename, lineno);] + This probe is fired when an exception is raised. + + classname is the class name of the raised exception (string) + filename the name of the file where the exception was raised (string) + lineno the line number in the file where the exception was raised (int) + +[ruby:::object-create(classname, filename, lineno);] + This probe is fired when an object is about to be allocated. + + classname the class of the allocated object (string) + filename the name of the file where the object is allocated (string) + lineno the line number in the file where the object is allocated (int) + +[ruby:::array-create(length, filename, lineno);] + This probe is fired when an Array is about to be allocated. + + length the size of the array (long) + filename the name of the file where the array is allocated (string) + lineno the line number in the file where the array is allocated (int) + +[ruby:::hash-create(length, filename, lineno);] + This probe is fired when a Hash is about to be allocated. + + length the size of the hash (long) + filename the name of the file where the hash is allocated (string) + lineno the line number in the file where the hash is allocated (int) + +[ruby:::string-create(length, filename, lineno);] + This probe is fired when a String is about to be allocated. + + length the size of the string (long) + filename the name of the file where the string is allocated (string) + lineno the line number in the file where the string is allocated (int) + +[ruby:::symbol-create(str, filename, lineno);] + This probe is fired when a Symbol is about to be allocated. + + str the contents of the symbol (string) + filename the name of the file where the string is allocated (string) + lineno the line number in the file where the string is allocated (int) + +[ruby:::parse-begin(sourcefile, lineno);] + Fired just before parsing and compiling a source file. + + sourcefile the file being parsed (string) + lineno the line number where the source starts (int) + +[ruby:::parse-end(sourcefile, lineno);] + Fired just after parsing and compiling a source file. + + sourcefile the file being parsed (string) + lineno the line number where the source ended (int) + +[ruby:::gc-mark-begin();] + Fired at the beginning of a mark phase. + +[ruby:::gc-mark-end();] + Fired at the end of a mark phase. + +[ruby:::gc-sweep-begin();] + Fired at the beginning of a sweep phase. + +[ruby:::gc-sweep-end();] + Fired at the end of a sweep phase. + + Index: ChangeLog =================================================================== --- ChangeLog (revision 43901) +++ ChangeLog (revision 43902) @@ -1,3 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Thu Nov 28 21:43:48 2013 Zachary Scott <e@z...> + + * doc/dtrace_probes.rdoc: [DOC] Import dtrace probes doc from wiki + Thu Nov 28 21:17:32 2013 Zachary Scott <e@z...> * doc/contributing.rdoc: [DOC] Add heading above ChangeLog tips to -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/