Skip to content

Commit

Permalink
runcores: fix docs, match docs with implementation and vice versa
Browse files Browse the repository at this point in the history 
use docs/running.pod as description for the runcore, debugging and
optimization options.
add missing docs for the runcores.

we already have a new parrot manpage for the rest.  allow the old runcores
in the implementation as described in the docs.
but disable the exec runcore, as it is different from the jit runcore.
there is now side-effect of producing a native executable (as of now).
  • Loading branch information
Reini Urban committed Mar 8, 2014
1 parent 8e19822 commit b1de450
Show file tree
Hide file tree
Showing 4 changed files with 78 additions and 140 deletions.
152 changes: 42 additions & 110 deletions docs/running.pod
View file
@@ -1,22 +1,27 @@
# Copyright (C) 2001-2012, Parrot Foundation.
# Copyright (C) 2001-2014, Parrot Foundation.

=pod

=head1 NAME

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

=head1 SYNOPSIS

parrot [-options] <file> [arguments ...]
parrot -R, --runcore <CORE> -O<level> -D<flags> -d<flags> -t<flags>

=head1 DESCRIPTION

This document describes Parrot's command line options.
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)>

=head1 VERSION
=head1 DESCRIPTION

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

=head1 ENVIRONMENT

Expand All @@ -39,13 +44,9 @@ Turn on the I<--gc-debug> flag.

=over 4

=item -O[level]

Valid optimizer levels: C<-O>, C<-O1>, C<-O2>, C<-Op>, C<-Oc>

=item B<-O>[level]

Valid optimizer levels: C<-O>, C<-O1>, C<-O2>
Valid optimizer levels: C<-O>, C<-O1>, C<-O2>, C<-Op>, C<-Oc>

C<-O1> enables the pre_optimizer, runs before control flow graph (CFG) is built.
It includes strength reduction and rewrites certain if/branch/label constructs.
Expand All @@ -55,46 +56,19 @@ removal of unused labels and dead code.

C<-Op> applies C<-O2> to pasm files also.

C<-Oc> does tailcall optimizations.

The old options C<-Oc> and C<-Oj> are currently ineffective.

C<-O> defaults to C<-O1>.

=item -a, --pasm

Assume PASM input on stdin.

=item -c, --pbc

Assume PBC file on stdin, run it.

=item -h, --help

Print command line option summary.

=item --help-debug

Print debugging and tracing flag bits summary.

=item -o outputfile, --output=outputfile

Act like an assembler. Don't run code, unless B<-r> is given too. If the
outputfile ends with F<.pbc>, a PBC file is written. If it ends with F<.pasm>,
a PASM output is generated, even from PASM input.

=item --output-pbc

Act like an assembler, but always output bytecode, even if the output file does
not end in F<.pbc>

=item -r, --run-pbc

Only useful after C<-o> or C<--output-pbc>. Run the program from the compiled
in-memory image. If two C<-r> options are given, the F<.pbc> file is read from
disc and run. This is mainly needed for tests.

=item -y, --yydebug

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

=item -v, --verbose

Expand All @@ -106,23 +80,12 @@ Turn on compiler verbosity.

Turn on compiler debug flags. I<See> C<parrot --help-debug> for available flag bits.

=item -V, --version

Print version information and exit.

=item -E, --pre-process-only

Preprocess source file (expand macros) and print result to stdout:

$ parrot -E t/op/macro_10.pasm
$ parrot -E t/op/macro_10.pasm | parrot -- -

=back

=head2 Runcore Options

These options select the runcore, which is useful for performance tuning and
debugging. See L<About runcores> for details.
debugging. See L<ABOUT RUNCORES> for details.

=over 4

Expand All @@ -136,26 +99,40 @@ may be available on your system:

slow, bounds bounds checking core

trace bounds checking core w/ trace info (see 'parrot --help-debug')
trace bounds checking core with trace info

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

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

The C<jit>, C<switch-jit>, and C<cgp-jit> options are currently aliases for the
C<fast>, C<switch>, and C<cgp> options, respectively. We do not recommend
their use in new code; they will continue working for existing code per our
deprecation policy.
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 C<debugger> runcore is used by debugger frontends.

See F<src/runcore/cores.c> for details.

=item -p, --profile

Run with the slow core and print an execution profile.

=item -t, --trace

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

=back

Expand All @@ -172,11 +149,6 @@ Turn on warnings. See C<parrot --help-debug> for available flag bits.
Turn on interpreter debug flag. See C<parrot --help-debug> for available flag
bits.

=item --hash-seed <hexnum>

Sets the hash seed to the provided value. Only useful for debugging
intermittent failures, and harmful in production.

=item --gc-debug

Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
Expand All @@ -193,44 +165,8 @@ quickly become exhausted.
Free all memory of the last interpreter. This is useful when running leak
checkers.

=item -., --wait

Read a keystroke before starting. This is useful when you want to attach a
debugger on platforms such as Windows.

=item --runtime-prefix

Print the runtime prefix path and exit.

=item -L path

Add C<path> to the library search path

=item --numthreads <number>

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


=back

=head2 <file>

If the file ends in F<.pbc> it will be interpreted immediately.

If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
parsed as PIR code. In both cases, it will then be run, unless the C<-o> flag
was given.

If the C<file> is a single dash, input from C<stdin> is read.

=head2 [arguments ...]

Optional arguments passed to the running program as ARGV. The program is
assumed to know what to do with these.

=head1 GENERATED FILES

=head1 ABOUT RUNCORES

The runcore (or runloop) tells Parrot how to find the C code that implements
Expand Down Expand Up @@ -284,8 +220,4 @@ full bounds checking, and also printing runtime information to stderr.
ass ... assemble sourcefile
obj .. produce native (ELF) object file for the EXEC subsystem

=head1 FILES

F<frontend/parrot/main.c>

=cut
25 changes: 17 additions & 8 deletions src/embed/api.c
View file
Expand Up @@ -187,22 +187,31 @@ Parrot_api_set_runcore(Parrot_PMC interp_pmc, ARGIN(const char * corename),
else {
if (STREQ(corename, "slow") || STREQ(corename, "bounds"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "slow"));
else if (STREQ(corename, "fast") || STREQ(corename, "jit") || STREQ(corename, "function"))
else if (STREQ(corename, "fast")
|| STREQ(corename, "function")
|| STREQ(corename, "cgp")
|| STREQ(corename, "switch"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "fast"));
else if (STREQ(corename, "subprof_sub"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "subprof_sub"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "subprof_hll") || STREQ(corename, "subprof"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "subprof_hll"));
else if (STREQ(corename, "subprof_ops"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "subprof_ops"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
#if 0
else if (STREQ(corename, "exec"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "exec"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
#endif
else if (STREQ(corename, "trace"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "slow"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "profiling"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "profiling"));
else if (STREQ(corename, "gcdebug"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "gcdebug"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "gc_debug"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "jit")
|| STREQ(corename, "cgp-jit")
|| STREQ(corename, "switch-jit"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "fast"));
else
Parrot_ex_throw_from_c_args(interp, NULL, 1, "Invalid runcore type %s", corename);
}
Expand Down
39 changes: 18 additions & 21 deletions src/runcore/cores.c
View file
Expand Up @@ -11,10 +11,10 @@ During execution, the runcore is like the heart of Parrot. The runcore
controls calling the various opcodes with the correct data, and making
sure that program flow moves properly. Some runcores, such as the
I<precomputed C goto runcore> are optimized for speed and don't perform
many tasks beyond finding and dispatching opcodes. Other runcores,
such as the I<GC-Debug>, I<debug> and I<profiling> runcores help with
typical software maintenance and analysis tasks. We'll talk about all
of these throughout the chapter.
many tasks beyond finding and dispatching opcodes. Other runcores, such as
the I<trace>, I<gc_debug>, I<debugger> and I<profiling> runcores help with
typical software maintenance and analysis tasks. We'll talk about all of
these throughout the chapter.
Runcores must pass execution to each opcode in the incoming bytecode
stream. This is called I<dispatching> the opcodes. Because the different
Expand Down Expand Up @@ -211,24 +211,20 @@ printed to the STDERR output for later analysis.
=head2 GC Debug Core
Parrot's garbage collector has been known as a weakness in the system
for several years. In fact, the garbage collector and memory management
subsystem was one of the last systems to be improved and rewritten before
the release of version 1.0. It's not that garbage collection isn't
important, but instead that it was so hard to do earlier in the project.
The older Parrot's garbage collectors has been known as weakness in the
system for several years. Early on when the GC was such a weakness, and
later when the GC was under active development, it was useful to have an
operational mode that would really exercise the GC and find bugs that
otherwise could hide by sheer chance. The GC debug runcore was this
tool. The core executes a complete collection iteration between every
single opcode. The throughput performance is terrible, but that's not the
point: it's almost guaranteed to find problems in the memory system if
they exist.
Early on when the GC was such a weakness, and later when the GC was under
active development, it was useful to have an operational mode that would
really exercise the GC and find bugs that otherwise could hide by sheer
chance. The GC debug runcore was this tool. The core executes a complete
collection iteration between every single opcode. The throughput
performance is terrible, but that's not the point: it's almost guaranteed
to find problems in the memory system if they exist.
=head2 Debugger Core
=head2 Debug Core
The debug core works like a normal software debugger, such as GDB. The
debug core executes each opcode, and then prompts the user to enter a
The debugger core works like a normal software debugger, such as GDB. The
debugger core executes each opcode, and then prompts the user to enter a
command. These commands can be used to continue execution, step to the
next opcode, or examine and manipulate data from the executing program.
Expand Down Expand Up @@ -678,7 +674,7 @@ runops_gc_debug_core(PARROT_INTERP, SHIM(Parrot_runcore_t *runcore), ARGIN(opcod
=item C<static opcode_t * runops_debugger_core(PARROT_INTERP, Parrot_runcore_t
*runcore, opcode_t *pc)>
Used by the debugger, under construction
Used by the debugger, under construction.
=cut
Expand Down Expand Up @@ -762,6 +758,7 @@ get_core_op_lib_init(SHIM_INTERP, ARGIN(Parrot_runcore_t *runcore))
*runcore, opcode_t *pc)>
Runs the native executable version of the specified opcode.
Currently disabled.
=cut
Expand Down
2 changes: 1 addition & 1 deletion src/runcore/main.c
View file
Expand Up @@ -70,7 +70,7 @@ Parrot_runcore_init(PARROT_INTERP)
Parrot_runcore_fast_init(interp);

Parrot_runcore_subprof_init(interp);
Parrot_runcore_exec_init(interp);
/* Parrot_runcore_exec_init(interp); */
Parrot_runcore_gc_debug_init(interp);
Parrot_runcore_debugger_init(interp);

Expand Down

0 comments on commit b1de450

Please sign in to comment.