Module: Debugger

Defined in:
ext/ruby_debug.c

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.



1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
 
# File 'ext/ruby_debug.c', line 1248

static VALUE
debug_add_breakpoint(int argc, VALUE *argv, VALUE self)
{
    VALUE result;

    debug_check_started();

    result = create_breakpoint_from_args(argc, argv, ++bkp_count);
    rb_ary_push(breakpoints, result);
    return result;
}

.breakpoints ⇒ Array

Returns an array of breakpoints.

Returns:

  • (Array) 


1296
1297
1298
1299
1300
1301
1302
 
# File 'ext/ruby_debug.c', line 1296

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) 


1311
1312
1313
1314
1315
1316
1317
 
# File 'ext/ruby_debug.c', line 1311

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

    return catchpoint;
}

.checkpoint=(string) ⇒ String

Sets checkpoint.

Returns:

  • (String) 


1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
 
# File 'ext/ruby_debug.c', line 1325

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) 


1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
 
# File 'ext/ruby_debug.c', line 1415

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



1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
 
# File 'ext/ruby_debug.c', line 1380

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 ⇒ Object

:nodoc:



1601
1602
1603
1604
1605
 
# File 'ext/ruby_debug.c', line 1601

static VALUE
debug_debug(VALUE self)
{
    return debug;
}

.debug=(value) ⇒ Object

:nodoc:



1608
1609
1610
1611
1612
1613
 
# File 'ext/ruby_debug.c', line 1608

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

.debug_at_exit { ... } ⇒ Proc

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

Yields:

Returns:

  • (Proc) 


1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
 
# File 'ext/ruby_debug.c', line 1711

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, stop = false) ⇒ nil

Same as Kernel#load but resets current context’s frames. stop parameter force the debugger to stop at the first line of code in the file FOR INTERNAL USE ONLY.

Returns:

  • (nil) 


1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
 
# File 'ext/ruby_debug.c', line 1630

static VALUE
debug_debug_load(int argc, VALUE *argv, VALUE self)
{
    VALUE file, stop, context;
    debug_context_t *debug_context;

    if(rb_scan_args(argc, argv, "11", &file, &stop) == 1)
      stop = Qfalse;

    debug_start(self);
    context = debug_current_context(self);
    Data_Get_Struct(context, debug_context_t, debug_context);
    debug_context->stack_size = 0;
    if(RTEST(stop))
      debug_context->stop_next = 1;
    rb_load(file, 0);

    debug_stop(self);
    return Qnil;
}

.keep_frame_binding=(bool) ⇒ Object

Setting to true will make the debugger create frame bindings.



1593
1594
1595
1596
1597
1598
 
# File 'ext/ruby_debug.c', line 1593

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) 


1581
1582
1583
1584
1585
 
# File 'ext/ruby_debug.c', line 1581

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

.last_interrupted ⇒ Object

Returns last debugged context.



1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
 
# File 'ext/ruby_debug.c', line 1359

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.



1566
1567
1568
1569
1570
1571
1572
1573
 
# File 'ext/ruby_debug.c', line 1566

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) 


1553
1554
1555
1556
1557
 
# File 'ext/ruby_debug.c', line 1553

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.



1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
 
# File 'ext/ruby_debug.c', line 1267

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:



1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
 
# File 'ext/ruby_debug.c', line 1491

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


1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
 
# File 'ext/ruby_debug.c', line 1672

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) 


1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
 
# File 'ext/ruby_debug.c', line 1147

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) 


382
383
384
385
386
 
# File 'ext/ruby_debug.c', line 382

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) 


1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
 
# File 'ext/ruby_debug.c', line 1180

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:



1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
 
# File 'ext/ruby_debug.c', line 1453

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);
        context_suspend_0(debug_context);
    }
    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.



1399
1400
1401
1402
1403
1404
1405
1406
1407
 
# File 'ext/ruby_debug.c', line 1399

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) 


1528
1529
1530
1531
1532
 
# File 'ext/ruby_debug.c', line 1528

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

.tracing=(bool) ⇒ Object

Sets the global tracing flag.



1540
1541
1542
1543
1544
1545
 
# File 'ext/ruby_debug.c', line 1540

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