summaryrefslogtreecommitdiff
path: root/vm_trace.c
diff options
context:
space:
mode:
authorko1 <ko1@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2015-04-15 08:40:25 +0000
committerko1 <ko1@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2015-04-15 08:40:25 +0000
commit0e7889959191ba74307ef450817833164eddb9f4 (patch)
treec171afdc7df3162507e9d0e571e3201cc2eae264 /vm_trace.c
parentd9a2b3480ef03b79ea9070de0646d2372491a915 (diff)
* vm_trace.c (rb_tracepoint_new): Add documentation for
rb_tracepoint_new C level API [ci skip] Provided by @emilsoman. [fix GH-869] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@50321 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'vm_trace.c')
-rw-r--r--vm_trace.c30
1 files changed, 30 insertions, 0 deletions
diff --git a/vm_trace.c b/vm_trace.c
index e50ea99..a186e0d 100644
--- a/vm_trace.c
+++ b/vm_trace.c
@@ -1171,6 +1171,36 @@ tracepoint_new(VALUE klass, rb_thread_t *target_th, rb_event_flag_t events, void
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)
{