NAME

docs/running.pod - Parrot runcore, debugging and optimizer options

SYNOPSIS

    parrot -R, --runcore <CORE> -O<level> -D<flags> -d<flags> -t<flags>

    parrot -R fast
    parrot -R slow
    parrot -R trace | -t
    parrot -R profiling
    parrot -R subprof
    parrot --gc-debug
    parrot -R jit      I<(currently disabled)>
    parrot -R exec     I<(currently disabled)>

DESCRIPTION

This document describes Parrot's runcore, debugging and optimizer options.

ENVIRONMENT

PARROT_RUNTIME

If this environment variable is set, parrot will use this path as its runtime prefix instead of the compiled in path.

PARROT_GC_DEBUG

Turn on the --gc-debug flag.

OPTIONS

Assembler/compiler options

-O[level]

Valid optimizer levels: -O, -O1, -O2, -Op, -Oc-O1 enables the pre_optimizer, runs before control flow graph (CFG) is built. It includes strength reduction and rewrites certain if/branch/label constructs.-O2 runs afterwards, handles constant propagation, jump optimizations, removal of unused labels and dead code.-Op applies -O2 to pasm files also.-Oc does tailcall optimizations.The old options -Oc and -Oj are currently ineffective.-O defaults to -O1.

--help-debug

Print debugging and tracing flag bits summary.

-y, --yydebug

Turn on yydebug in yacc/bison. Same as -d0004

-v, --verbose

Turn on compiler verbosity.

-d[=HEXFLAGS]

--imcc-debug[=HEXFLAGS]

Turn on compiler debug flags. See parrot --help-debug for available flag bits.

Runcore Options

These options select the runcore, which is useful for performance tuning and debugging. See "ABOUT RUNCORES" for details.

-R, --runcore CORE

Select the runcore. The following cores are available in Parrot, but not all may be available on your system:

  fast          bare-bones core without bounds-checking or
                context-updating (default)

  slow, bounds  bounds checking core

  trace         bounds checking core with trace info

  profiling     Rudimentary profiling support.
                See L<docs/dev/profiling.pod>

  subprof       Better subroutine-level profilers
  subprof_sub
  subprof_hll
  subprof_ops
                See POD in F<src/runcore/subprof.c>

  gc_debug      Does a full GC on each op.

Older currently ignored options include:

  jit, switch-jit, cgp-jit, switch, cgp, function, exec

We do not recommend their use in new code; they will continue working for existing code per our deprecation policy. The options function, cgp, switch, and jit, switch-jit, cgp-jit are currently aliases for fast.The additional internal debugger runcore is used by debugger frontends.See src/runcore/cores.c for details.

-p, --profile

Run with the slow core and print an execution profile.

-t, --trace

Run with the trace core and print trace information to stderr. See parrot --help-debug for available flag bits.

VM Options

-w, --warnings

Turn on warnings. See parrot --help-debug for available flag bits.

-D, --parrot-debug

Turn on interpreter debug flag. See parrot --help-debug for available flag bits.

--gc-debug

Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC subsystem and can slow down execution considerably.

-G, --no-gc

This turns off GC. This may be useful to find GC related bugs. Don't use this option for longer running programs: as memory is no longer recycled, it may quickly become exhausted.

--gc-nursery-size=percent

Default: 2

--gc-dynamic-threshold=percent

Default: 75

--gc-min-threshold=MB

Default: 4

--leak-test, --destroy-at-end

Free all memory of the last interpreter. This is useful when running leak checkers.

--numthreads=number

Overrides the automatically detected number of CPU cores to set the number of OS threads. Minimum number: 2

ABOUT RUNCORES

The runcore (or runloop) tells Parrot how to find the C code that implements each instruction. Parrot provides more than one way to do this, partly because no single runcore will perform optimally on all architectures (or even for all problems on a given architecture), and partly because some of the runcores have specific debugging and tracing capabilities.

In the "slow" or "bounds" runcore, each opcode is a separate C function. That's pretty easy in pseudocode:

    slow_runcore( op ):
        while ( op ):
            op = op_function( op )
            check_for_events()

The old GC debugging runcore was similar:

    gcdebug_runcore( op ):
        while ( op ):
            perform_full_gc_run()
            op = op_function( op )
            check_for_events()

Of course, this is much slower, but is extremely helpful for pinning memory corruption problems that affect GC down to single-instruction resolution. See http://www.oreillynet.com/onlamp/blog/2007/10/debugging_gc_problems_in_parro.html for more information.

The trace and profile cores are also based on the "slow" core, doing full bounds checking, and also printing runtime information to stderr.

OPERATION TABLE

 Command Line          Action         Output
 ---------------------------------------------
 parrot x.pir          run
 parrot x.pasm         run
 parrot x.pbc          run
 -o x.pasm x.pir       ass            x.pasm
 -o x.pasm y.pasm      ass            x.pasm
 -o x.pbc  x.pir       ass            x.pbc
 -o x.pbc  x.pasm      ass            x.pbc
 -o x.pbc -r x.pasm    ass/run pasm   x.pbc
 -o x.pbc -r -r x.pasm ass/run pbc    x.pbc
 -o x.o    x.pbc       obj

... where the possible actions are:

  run ... yes, run the program
  ass ... assemble sourcefile
  obj ..  produce native (ELF) object file for the EXEC subsystem