ko1	2015-04-15 17:40:25 +0900 (Wed, 15 Apr 2015)

  New Revision: 50321

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=50321

  Log:
    * vm_trace.c (rb_tracepoint_new): Add documentation for
      rb_tracepoint_new C level API [ci skip]
      Provided by @emilsoman. [fix GH-869]

  Modified files:
    trunk/ChangeLog
    trunk/vm_trace.c
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 50320)
+++ ChangeLog	(revision 50321)
@@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Wed Apr 15 17:36:51 2015  Koichi Sasada  <ko1@a...>
+
+	* vm_trace.c (rb_tracepoint_new): Add documentation for
+	  rb_tracepoint_new C level API [ci skip]
+	  Provided by @emilsoman. [fix GH-869]
+
 Wed Apr 15 10:37:40 2015  SHIBATA Hiroshi  <hsbt@r...>
 
 	* doc/contributors.rdoc: fix a typo. Patch by @davydovanton
Index: vm_trace.c
===================================================================
--- vm_trace.c	(revision 50320)
+++ vm_trace.c	(revision 50321)
@@ -1171,6 +1171,36 @@ tracepoint_new(VALUE klass, rb_thread_t https://github.com/ruby/ruby/blob/trunk/vm_trace.c#L1171
     return tpval;
 }
 
+/*
+ * Creates a tracepoint by registering a callback function for one or more
+ * tracepoint events. Once the tracepoint is created, you can use
+ * rb_tracepoint_enable to enable the tracepoint.
+ *
+ * Parameters:
+ *   1. VALUE target_thval - Meant for picking the thread in which the tracepoint
+ *      is to be created. However, current implementation ignore this parameter,
+ *      tracepoint is created for all threads. Simply specify Qnil.
+ *   2. rb_event_flag_t events - Event(s) to listen to.
+ *   3. void (*func)(VALUE, void *) - A callback function.
+ *   4. void *data - Void pointer that will be passed to the callback function.
+ *
+ * When the callback function is called, it will be passed 2 parameters:
+ *   1)VALUE tpval - the TracePoint object from which trace args can be extracted.
+ *   2)void *data - A void pointer which helps to share scope with the callback function.
+ *
+ * It is important to note that you cannot register callbacks for normal events and internal events
+ * simultaneously because they are different purpose.
+ * You can use any Ruby APIs (calling methods and so on) on normal event hooks.
+ * However, you can not use any Ruby APIs (even object creations).
+ * This is why we can't specify internal events by TracePoint directly.
+ * Limitations are MRI version specific.
+ *
+ * Example:
+ *   rb_tracepoint_new(Qnil, RUBY_INTERNAL_EVENT_NEWOBJ | RUBY_INTERNAL_EVENT_FREEOBJ, obj_event_i, data);
+ *
+ *   In this example, a callback function obj_event_i will be registered for
+ *   internal events RUBY_INTERNAL_EVENT_NEWOBJ and RUBY_INTERNAL_EVENT_FREEOBJ.
+ */
 VALUE
 rb_tracepoint_new(VALUE target_thval, rb_event_flag_t events, void (*func)(VALUE, void *), void *data)
 {

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/