Module: Debugger

Defined in:
ext/ruby_debug.c

Defined Under Namespace

Classes: ThreadsTable

Constant Summary collapse

VERSION = 
rb_str_new2(DEBUG_VERSION)

Class Method Summary collapse

Class Method Details

.add_breakpoint(source, pos, condition = nil) ⇒ Object

Adds a new breakpoint. source is a name of a file or a class. pos is a line number or a method name if source is a class name. condition is a string which is evaluated to true when this breakpoint is activated.



933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
 
# File 'ext/ruby_debug.c', line 933

static VALUE
debug_add_breakpoint(int argc, VALUE *argv, VALUE self)
{
    VALUE source, pos, expr;
    VALUE result;
    debug_breakpoint_t *breakpoint;
    int type;

    debug_check_started();
    
    if(rb_scan_args(argc, argv, "21", &source, &pos, &expr) == 2)
    {
        expr = Qnil;
    }
    type = FIXNUM_P(pos) ? BP_POS_TYPE : BP_METHOD_TYPE;
    if(type == BP_POS_TYPE)
        source = StringValue(source);
    else
        pos = StringValue(pos);
    breakpoint = ALLOC(debug_breakpoint_t);
    breakpoint->id = ++bkp_count;
    breakpoint->source = source;
    breakpoint->type = type;
    if(type == BP_POS_TYPE)
        breakpoint->pos.line = FIX2INT(pos);
    else
        breakpoint->pos.mid = rb_intern(RSTRING(pos)->ptr);
    breakpoint->expr = NIL_P(expr) ? expr: StringValue(expr);
    result = Data_Wrap_Struct(cBreakpoint, breakpoint_mark, xfree, breakpoint);
    rb_ary_push(breakpoints, result);
    return result;
}

.breakpoints ⇒ Array

Returns an array of breakpoints.

Returns:

  • (Array) 


1002
1003
1004
1005
1006
1007
1008
 
# File 'ext/ruby_debug.c', line 1002

static VALUE
debug_breakpoints(VALUE self)
{
    debug_check_started();

    return breakpoints;
}

.checkpoint ⇒ String

Returns a current checkpoint, which is a name of exception that will trigger a debugger when raised.

Returns:

  • (String) 


1017
1018
1019
1020
1021
1022
1023
 
# File 'ext/ruby_debug.c', line 1017

static VALUE
debug_catchpoint(VALUE self)
{
    debug_check_started();

    return catchpoint;
}

.checkpoint=(string) ⇒ String

Sets checkpoint.

Returns:

  • (String) 


1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
 
# File 'ext/ruby_debug.c', line 1031

static VALUE
debug_set_catchpoint(VALUE self, VALUE value)
{
    debug_check_started();

    if (!NIL_P(value) && TYPE(value) != T_STRING) {
        rb_raise(rb_eTypeError, "value of checkpoint must be String");
    }
    if(NIL_P(value))
    catchpoint = Qnil;
    else
    catchpoint = rb_str_dup(value);
    return value;
}

.contexts ⇒ Array

Returns an array of all contexts.

Returns:

  • (Array) 


1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
 
# File 'ext/ruby_debug.c', line 1105

static VALUE
debug_contexts(VALUE self)
{
    volatile VALUE list;
    volatile VALUE new_list;
    VALUE thread, context;
    threads_table_t *threads_table;
    debug_context_t *debug_context;
    int i;

    debug_check_started();

    new_list = rb_ary_new();
    list = rb_funcall(rb_cThread, idList, 0);
    for(i = 0; i < RARRAY(list)->len; i++)
    {
        thread = rb_ary_entry(list, i);
        context = thread_context_lookup(thread);
        rb_ary_push(new_list, context);
    }
    threads_table_clear(threads_tbl);
    Data_Get_Struct(threads_tbl, threads_table_t, threads_table);
    for(i = 0; i < RARRAY(new_list)->len; i++)
    {
        context = rb_ary_entry(new_list, i);
        Data_Get_Struct(context, debug_context_t, debug_context);
        st_insert(threads_table->tbl, debug_context->thread_id, context);
    }

    return new_list;
}

.current_context ⇒ Object

Returns current context. Note: Debugger.current_context.thread == Thread.current



1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
 
# File 'ext/ruby_debug.c', line 1086

static VALUE
debug_current_context(VALUE self)
{
    VALUE thread, context;

    debug_check_started();

    thread = rb_thread_current();
    context = thread_context_lookup(thread);

    return context;
}

.debug_at_exit { ... } ⇒ Proc

Register at_exit hook which is escaped from the debugger. FOR INTERNAL USE ONLY.

Yields:

Returns:

  • (Proc) 


1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
 
# File 'ext/ruby_debug.c', line 1378

static VALUE
debug_at_exit(VALUE self)
{
    VALUE proc;
    if (!rb_block_given_p()) {
        rb_raise(rb_eArgError, "called without a block");
    }
    proc = rb_block_proc();
    rb_set_end_proc(debug_at_exit_i, proc);
    return proc;
}

.debug_load(file) ⇒ nil

Same as Kernel#load but resets current context’s frames. FOR INTERNAL USE ONLY. Use Debugger.post_mortem method instead.

Returns:

  • (nil) 


1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
 
# File 'ext/ruby_debug.c', line 1301

static VALUE
debug_debug_load(VALUE self, VALUE file)
{
    VALUE context;
    debug_context_t *debug_context;
    
    debug_start(self);
    
    context = debug_current_context(self);
    Data_Get_Struct(context, debug_context_t, debug_context);
    rb_ary_clear(debug_context->frames);
    rb_load(file, 0);
    
    debug_stop(self);
    return Qnil;
}

.post_mortem=(bool) ⇒ Object

Setting to true will make the debugger keep frame bindings.



1287
1288
1289
1290
1291
1292
 
# File 'ext/ruby_debug.c', line 1287

static VALUE
debug_set_keep_frame_info(VALUE self, VALUE value)
{
    keep_frame_info = RTEST(value) ? Qtrue : Qfalse;
    return value;
}

.post_mortem? ⇒ Boolean

Returns true if the debugger will collect frame bindings.

Returns:

  • (Boolean) 


1275
1276
1277
1278
1279
 
# File 'ext/ruby_debug.c', line 1275

static VALUE
debug_keep_frame_info(VALUE self)
{
    return keep_frame_info;
}

.last_interrupted ⇒ Object

Returns last debugged context.



1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
 
# File 'ext/ruby_debug.c', line 1065

static VALUE
debug_last_interrupted(VALUE self)
{
    VALUE result = Qnil;
    threads_table_t *threads_table;

    debug_check_started();

    Data_Get_Struct(threads_tbl, threads_table_t, threads_table);
    
    st_foreach(threads_table->tbl, find_last_context_func, (st_data_t)&result);
    return result;
}

.post_mortem=(bool) ⇒ Object

Sets post-moterm flag. FOR INTERNAL USE ONLY.



1260
1261
1262
1263
1264
1265
1266
1267
 
# File 'ext/ruby_debug.c', line 1260

static VALUE
debug_set_post_mortem(VALUE self, VALUE value)
{
    debug_check_started();

    post_mortem = RTEST(value) ? Qtrue : Qfalse;
    return value;
}

.post_mortem? ⇒ Boolean

Returns true if post-moterm debugging is enabled.

Returns:

  • (Boolean) 


1247
1248
1249
1250
1251
 
# File 'ext/ruby_debug.c', line 1247

static VALUE
debug_post_mortem(VALUE self)
{
    return post_mortem;
}

.remove_breakpoint(id) ⇒ Object

Removes breakpoint by its id. id is an identificator of a breakpoint.



973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
 
# File 'ext/ruby_debug.c', line 973

static VALUE
debug_remove_breakpoint(VALUE self, VALUE id_value)
{
    int i;
    int id;
    VALUE breakpoint;
    debug_breakpoint_t *debug_breakpoint;
    
    id = FIX2INT(id_value);
    
    for( i = 0; i < RARRAY(breakpoints)->len; i += 1 )
    {
        breakpoint = rb_ary_entry(breakpoints, i);
        Data_Get_Struct(breakpoint, debug_breakpoint_t, debug_breakpoint);
        if(debug_breakpoint->id == id)
        {
            rb_ary_delete_at(breakpoints, i);
            return breakpoint;
        }
    }
    return Qnil;
}

.resume ⇒ Debugger

Resumes all contexts.

Returns:



1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
 
# File 'ext/ruby_debug.c', line 1181

static VALUE
debug_resume(VALUE self)
{
    VALUE current, context;
    VALUE saved_crit;
    VALUE context_list;
    debug_context_t *debug_context;
    int i;

    debug_check_started();

    saved_crit = rb_thread_critical;
    rb_thread_critical = Qtrue;
    context_list = debug_contexts(self);

    current = thread_context_lookup(rb_thread_current());
    for(i = 0; i < RARRAY(context_list)->len; i++)
    {
        context = rb_ary_entry(context_list, i);
        if(current == context)
            continue;
        Data_Get_Struct(context, debug_context_t, debug_context);
        if(CTX_FL_TEST(debug_context, CTX_FL_SUSPEND))
        {
            CTX_FL_UNSET(debug_context, CTX_FL_SUSPEND);
            rb_thread_run(context_thread_0(debug_context));
        }
    }
    rb_thread_critical = saved_crit;

    rb_thread_schedule();

    return self;
}

.skip { ... } ⇒ Object?

The code inside of the block is escaped from the debugger.

Yields:

Returns:

  • (Object, nil) 


1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
 
# File 'ext/ruby_debug.c', line 1339

static VALUE
debug_skip(VALUE self)
{
    if (!rb_block_given_p()) {
        rb_raise(rb_eArgError, "called without a block");
    }
    if(!IS_STARTED)
        return rb_yield(Qnil);
    set_current_skipped_status(Qtrue);
    return rb_ensure(rb_yield, Qnil, set_current_skipped_status, Qfalse);
}

.start ⇒ Boolean .start { ... } ⇒ Object

This method activates the debugger. If it’s called without a block it returns true, unless debugger was already started. If a block is given, it starts debugger and yields to block. When the block is finished executing it stops the debugger with Debugger.stop method.

Note that if you want to stop debugger, you must call Debugger.stop as many time as you called Debugger.start method.

Overloads:

  • .start ⇒ Boolean

    Returns:

    • (Boolean)
  • .start { ... } ⇒ Object

    Yields:

    Returns:

    • (Object) 


863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
 
# File 'ext/ruby_debug.c', line 863

static VALUE
debug_start(VALUE self)
{
    VALUE result;
    start_count++;
    
    if(IS_STARTED)
        result = Qfalse;
    else
    {
        breakpoints = rb_ary_new();
        locker      = Qnil;
        threads_tbl = threads_table_create();

        rb_add_event_hook(debug_event_hook, RUBY_EVENT_ALL);
        result = Qtrue;
    }
    
    if(rb_block_given_p())
        return rb_ensure(rb_yield, self, debug_stop_i, self);
    return result;
}

.started? ⇒ Boolean

Returns true the debugger is started.

Returns:

  • (Boolean) 


315
316
317
318
319
 
# File 'ext/ruby_debug.c', line 315

static VALUE
debug_is_started(VALUE self)
{
    return IS_STARTED ? Qtrue : Qfalse;
}

.stop ⇒ Boolean

This method disacivates the debugger. It returns true if the debugger is disacivated, otherwise it returns false.

Note that if you want to stop debugger, you must call Debugger.stop as many time as you called Debugger.start method.

Returns:

  • (Boolean) 


896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
 
# File 'ext/ruby_debug.c', line 896

static VALUE
debug_stop(VALUE self)
{
    debug_check_started();
    
    start_count--;
    if(start_count)
        return Qfalse;
    
    rb_remove_event_hook(debug_event_hook);

    locker      = Qnil;
    breakpoints = Qnil;
    threads_tbl = Qnil;

    return Qtrue;
}

.suspend ⇒ Debugger

Suspends all contexts.

Returns:



1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
 
# File 'ext/ruby_debug.c', line 1143

static VALUE
debug_suspend(VALUE self)
{
    VALUE current, context;
    VALUE saved_crit;
    VALUE context_list;
    debug_context_t *debug_context;
    int i;

    debug_check_started();

    saved_crit = rb_thread_critical;
    rb_thread_critical = Qtrue;
    context_list = debug_contexts(self);
    current = thread_context_lookup(rb_thread_current());

    for(i = 0; i < RARRAY(context_list)->len; i++)
    {
        context = rb_ary_entry(context_list, i);
        if(current == context)
            continue;
        Data_Get_Struct(context, debug_context_t, debug_context);
        CTX_FL_SET(debug_context, CTX_FL_SUSPEND);
    }
    rb_thread_critical = saved_crit;

    if(rb_thread_critical == Qfalse)
        rb_thread_schedule();

    return self;
}

.tracing ⇒ Boolean

Returns true if the global tracing is activated.

Returns:

  • (Boolean) 


1222
1223
1224
1225
1226
 
# File 'ext/ruby_debug.c', line 1222

static VALUE
debug_tracing(VALUE self)
{
    return tracing;
}

.tracing=(bool) ⇒ Object

Sets the global tracing flag.



1234
1235
1236
1237
1238
1239
 
# File 'ext/ruby_debug.c', line 1234

static VALUE
debug_set_tracing(VALUE self, VALUE value)
{
    tracing = RTEST(value) ? Qtrue : Qfalse;
    return value;
}