Prefer rb-fiber-scan-heap --limit N.

Author: samuel-williams-shopify

context/fiber-debugging.md

@@ -44,7 +44,7 @@ Fiber #1: <T_DATA@...> → <struct rb_fiber_struct@...>
 For large applications, limit the scan:
 
 ~~~
-(gdb) rb-fiber-scan-heap 10    # Find first 10 fibers only
+(gdb) rb-fiber-scan-heap --limit 10    # Find first 10 fibers only
 ~~~
 
 ### Caching Results

context/getting-started.md

@@ -87,6 +87,7 @@ This removes the source line from your `~/.gdbinit`.
 
 Ruby GDB provides specialized commands for debugging Ruby at multiple levels:
 
+- **Context Setup** (`rb-context`) - Get current execution context and set up convenience variables
 - **Object Inspection** (`rb-object-print`) - View Ruby objects, hashes, arrays, and structs with proper formatting
 - **Fiber Debugging** (`rb-fiber-*`) - Scan heap for fibers, inspect state, and switch contexts
 - **Stack Analysis** (`rb-stack-trace`) - Examine combined VM (Ruby) and C (native) stack frames

context/heap-debugging.md

@@ -373,7 +373,7 @@ Later in the same session, just load the cache:
 For production core dumps with millions of objects:
 
 ~~~
-(gdb) rb-fiber-scan-heap 20             # Find first 20 fibers only
+(gdb) rb-fiber-scan-heap --limit 20     # Find first 20 fibers only
 (gdb) rb-heap-scan --limit 100          # Find first 100 objects of any type
 ~~~
 

data/toolbox/fiber.py

@@ -228,10 +228,10 @@ def __init__(self):
 
     def usage(self):
         """Print usage information."""
-        print("Usage: rb-fiber-scan-heap [limit] [--cache [filename]] [--terminated]")
+        print("Usage: rb-fiber-scan-heap [--limit N] [--cache [filename]] [--terminated]")
         print("Examples:")
         print("  rb-fiber-scan-heap                    # Find all non-terminated fibers")
-        print("  rb-fiber-scan-heap 10                 # Find first 10 non-terminated fibers")
+        print("  rb-fiber-scan-heap --limit 10         # Find first 10 non-terminated fibers")
         print("  rb-fiber-scan-heap --terminated       # Include terminated fibers")
         print("  rb-fiber-scan-heap --cache            # Use fibers.json cache")
         print("  rb-fiber-scan-heap --cache my.json    # Use custom cache file")
@@ -309,17 +309,18 @@ def invoke(self, arg, from_tty):
         # Parse arguments using the robust parser
         arguments = command.parse_arguments(arg if arg else "")
 
-        # Get limit from first expression (positional argument)
+        # Get limit from --limit option
         limit = None
-        if arguments.expressions:
+        limit_str = arguments.get_option('limit')
+        if limit_str:
             try:
-                limit = int(arguments.expressions[0])
+                limit = int(limit_str)
                 if limit <= 0:
                     print("Error: limit must be positive")
                     self.usage()
                     return
             except ValueError:
-                print(f"Error: invalid limit '{arguments.expressions[0]}'")
+                print(f"Error: invalid limit '{limit_str}'")
                 self.usage()
                 return
 

fixtures/toolbox/gdb/fiber/can_scan_heap.gdb

@@ -21,7 +21,7 @@ set $fiber_value = argv[0]
 # Now scan the heap for fibers
 # We should find at least 1 fiber (the one we created)
 echo ===TOOLBOX-OUTPUT-START===\n
-rb-fiber-scan-heap 1
+rb-fiber-scan-heap --limit 1
 echo ===TOOLBOX-OUTPUT-END===\n
 
 quit

fixtures/toolbox/gdb/fiber/can_switch_by_index.gdb

@@ -18,7 +18,7 @@ run
 
 # Scan for fibers first
 echo ===TOOLBOX-OUTPUT-START===\n
-rb-fiber-scan-heap 1
+rb-fiber-scan-heap --limit 1
 echo \n
 rb-fiber-scan-switch 0
 echo ===TOOLBOX-OUTPUT-END===\n

fixtures/toolbox/lldb/fiber/can_scan_heap.lldb

@@ -9,7 +9,7 @@ run
 # Now scan the heap for fibers
 # We should find at least 1 fiber (the one we created)
 script print("===TOOLBOX-OUTPUT-START===")
-rb-fiber-scan-heap 1
+rb-fiber-scan-heap --limit 1
 script print("===TOOLBOX-OUTPUT-END===")
 
 quit

guides/fiber-debugging/readme.md

@@ -44,7 +44,7 @@ Fiber #1: <T_DATA@...> → <struct rb_fiber_struct@...>
 For large applications, limit the scan:
 
 ~~~
-(gdb) rb-fiber-scan-heap 10    # Find first 10 fibers only
+(gdb) rb-fiber-scan-heap --limit 10    # Find first 10 fibers only
 ~~~
 
 ### Caching Results

guides/getting-started/readme.md

@@ -87,6 +87,7 @@ This removes the source line from your `~/.gdbinit`.
 
 Ruby GDB provides specialized commands for debugging Ruby at multiple levels:
 
+- **Context Setup** (`rb-context`) - Get current execution context and set up convenience variables
 - **Object Inspection** (`rb-object-print`) - View Ruby objects, hashes, arrays, and structs with proper formatting
 - **Fiber Debugging** (`rb-fiber-*`) - Scan heap for fibers, inspect state, and switch contexts
 - **Stack Analysis** (`rb-stack-trace`) - Examine combined VM (Ruby) and C (native) stack frames

guides/heap-debugging/readme.md

@@ -373,7 +373,7 @@ Later in the same session, just load the cache:
 For production core dumps with millions of objects:
 
 ~~~
-(gdb) rb-fiber-scan-heap 20             # Find first 20 fibers only
+(gdb) rb-fiber-scan-heap --limit 20     # Find first 20 fibers only
 (gdb) rb-heap-scan --limit 100          # Find first 100 objects of any type
 ~~~