From 0e7889959191ba74307ef450817833164eddb9f4 Mon Sep 17 00:00:00 2001 From: ko1 Date: Wed, 15 Apr 2015 08:40:25 +0000 Subject: [PATCH] * 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 --- ChangeLog | 6 ++++++ vm_trace.c | 30 ++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/ChangeLog b/ChangeLog index cb2a0712f8..aef2c6dfbe 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +Wed Apr 15 17:36:51 2015 Koichi Sasada + + * 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 * doc/contributors.rdoc: fix a typo. Patch by @davydovanton diff --git a/vm_trace.c b/vm_trace.c index e50ea992f2..a186e0d364 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) {