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.



1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
 
# File 'ext/ruby_debug.c', line 1021

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) 


1090
1091
1092
1093
1094
1095
1096
 
# File 'ext/ruby_debug.c', line 1090

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) 


1105
1106
1107
1108
1109
1110
1111
 
# File 'ext/ruby_debug.c', line 1105

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

    return catchpoint;
}

.checkpoint=(string) ⇒ String

Sets checkpoint.

Returns:

  • (String) 


1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
 
# File 'ext/ruby_debug.c', line 1119

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) 


1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
 
# File 'ext/ruby_debug.c', line 1209

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);
        thread_context_lookup(thread, &context, NULL);
        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



1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
 
# File 'ext/ruby_debug.c', line 1174

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

    debug_check_started();

    thread = rb_thread_current();
    thread_context_lookup(thread, &context, NULL);

    return context;
}

.debug_at_exit { ... } ⇒ Proc

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

Yields:

Returns:

  • (Proc) 


1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
 
# File 'ext/ruby_debug.c', line 1482

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) 


1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
 
# File 'ext/ruby_debug.c', line 1405

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);
    debug_context->stack_size = 0;
    rb_load(file, 0);
    
    debug_stop(self);
    return Qnil;
}

.keep_frame_binding=(bool) ⇒ Object

Setting to true will make the debugger create frame bindings.



1391
1392
1393
1394
1395
1396
 
# File 'ext/ruby_debug.c', line 1391

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

.keep_frame_binding? ⇒ Boolean

Returns true if the debugger will collect frame bindings.

Returns:

  • (Boolean) 


1379
1380
1381
1382
1383
 
# File 'ext/ruby_debug.c', line 1379

static VALUE
debug_keep_frame_binding(VALUE self)
{
    return keep_frame_binding;
}

.last_interrupted ⇒ Object

Returns last debugged context.



1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
 
# File 'ext/ruby_debug.c', line 1153

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.



1364
1365
1366
1367
1368
1369
1370
1371
 
# File 'ext/ruby_debug.c', line 1364

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) 


1351
1352
1353
1354
1355
 
# File 'ext/ruby_debug.c', line 1351

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.



1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
 
# File 'ext/ruby_debug.c', line 1061

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:



1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
 
# File 'ext/ruby_debug.c', line 1285

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);

    thread_context_lookup(rb_thread_current(), &current, NULL);
    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) 


1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
 
# File 'ext/ruby_debug.c', line 1443

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) 


951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
 
# File 'ext/ruby_debug.c', line 951

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) 


356
357
358
359
360
 
# File 'ext/ruby_debug.c', line 356

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) 


984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
 
# File 'ext/ruby_debug.c', line 984

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:



1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
 
# File 'ext/ruby_debug.c', line 1247

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);
    thread_context_lookup(rb_thread_current(), &current, NULL);

    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;
}

.thread_context(thread) ⇒ Object

Returns context of the thread passed as an argument.



1193
1194
1195
1196
1197
1198
1199
1200
1201
 
# File 'ext/ruby_debug.c', line 1193

static VALUE
debug_thread_context(VALUE self, VALUE thread)
{
    VALUE context;
    
    debug_check_started();
    thread_context_lookup(thread, &context, NULL);
    return context;
}

.tracing ⇒ Boolean

Returns true if the global tracing is activated.

Returns:

  • (Boolean) 


1326
1327
1328
1329
1330
 
# File 'ext/ruby_debug.c', line 1326

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

.tracing=(bool) ⇒ Object

Sets the global tracing flag.



1338
1339
1340
1341
1342
1343
 
# File 'ext/ruby_debug.c', line 1338

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