--- Faster/Faster.pm	2006/03/10 18:39:26	1.12
+++ Faster/Faster.pm	2006/03/13 17:10:32	1.33
@@ -6,19 +6,56 @@
 
  use Faster;
 
+ perl -MFaster ...
+
 =head1 DESCRIPTION
 
+This module implements a very simple-minded "JIT" (or actually AIT, ahead
+of time compiler). It works by more or less translating every function it
+sees into a C program, compiling it and then replacing the function by the
+compiled code.
+
+As a result, startup times are immense, as every function might lead to a
+full-blown compilation.
+
+The speed improvements are also not great, you can expect 20% or so on
+average, for code that runs very often. The reason for this is that data
+handling is mostly being done by the same old code, it just gets called
+a bit faster. Regexes and string operations won't get faster. Airhtmetic
+doresn't become any faster. Just the operands and other stuff is put on
+the stack faster, and the opcodes themselves have a bit less overhead.
+
+Faster is in the early stages of development. Due to its design its
+relatively safe to use (it will either work or simply slowdown the program
+immensely, but rarely cause bugs).
+
+More intelligent algorithms (loop optimisation, type inference) could
+improve that easily, but requires a much more elaborate presentation and
+optimiser than what is in place. There are no plans to improve Faster in
+this way, yet, but it would provide a reasonably good place to start.
+
+Usage is very easy, just C<use Faster> and every function called from then
+on will be compiled.
+
+Right now, Faster can leave lots of F<*.c> and F<*.so> files in your
+F<$FASTER_CACHEDIR> (by default F<$HOME/.perl-faster-cache>), and it will
+even create those temporary files in an insecure manner, so watch out.
+
 =over 4
 
 =cut
 
 package Faster;
 
+no warnings;
+
 use strict;
 use Config;
 use B ();
-use Digest::MD5 ();
 use DynaLoader ();
+use Digest::MD5 ();
+use Storable ();
+use Fcntl ();
 
 BEGIN {
    our $VERSION = '0.01';
@@ -27,121 +64,122 @@
    XSLoader::load __PACKAGE__, $VERSION;
 }
 
+my $CACHEDIR =
+   $ENV{FASTER_CACHE}
+   || (exists $ENV{HOME} && "$ENV{HOME}/.perl-faster-cache")
+   || do {
+      require File::Temp;
+      File::Temp::tempdir (CLEANUP => 1)
+   };
+
 my $COMPILE = "$Config{cc} -c -I$Config{archlibexp}/CORE $Config{optimize} $Config{ccflags} $Config{cccdlflags}";
 my $LINK    = "$Config{ld} $Config{ldflags} $Config{lddlflags} $Config{ccdlflags}";
 my $LIBS    = "$Config{libs}";
 my $_o      = $Config{_o};
 my $_so     = ".so";
 
-my $opt_assert = 1;
+# we don't need no steenking PIC on x86
+$COMPILE =~ s/-f(?:PIC|pic)//g
+   if $Config{archname} =~ /^(i[3456]86)-/;
+
+my $opt_assert = $ENV{FASTER_DEBUG} > 1;
+my $verbose    = $ENV{FASTER_VERBOSE}+0;
+
+warn "Faster: CACHEDIR is $CACHEDIR\n" if $verbose > 2;
 
 our $source;
 
-my @ops;
-my $op;
-my $op_name;
-my @loop;
-
-my %flag;
-
-# complex flag steting is no longer required, rewrite this ugly code
-for (split /\n/, <<EOF) {
-   leavesub	unsafe
-   leavesublv	unsafe
-   return	unsafe
-   flip		unsafe
-   goto		unsafe
-   last		unsafe
-   redo		unsafe
-   next		unsafe
-   eval		unsafe
-   leaveeval	unsafe
-   entertry	unsafe
-   formline	unsafe
-   grepstart	unsafe
-   mapstart	unsafe
-   substcont	unsafe
-   entereval	unsafe noasync	todo
-   require	unsafe
-
-   mapstart	noasync
-   grepstart	noasync
-   match	noasync
-
-   last		noasync
-   next		noasync
-   redo		noasync
-   seq		noasync
-   pushmark	noasync extend=0
-   padsv	noasync extend=1
-   padav	noasync extend=1
-   padhv	noasync extend=1
-   padany	noasync extend=1
-   entersub	noasync
-   aassign	noasync
-   sassign	noasync
-   rv2av	noasync
-   rv2cv	noasync
-   rv2gv	noasync
-   rv2hv	noasync
-   refgen	noasync
-   nextstate	noasync
-   gv		noasync
-   gvsv		noasync
-   add		noasync
-   subtract	noasync
-   multiply	noasync
-   divide	noasync
-   complement	noasync
-   cond_expr	noasync
-   and		noasync
-   or		noasync
-   not		noasync
-   defined	noasync
-   method_named	noasync
-   preinc	noasync
-   postinc	noasync
-   predec	noasync
-   postdec	noasync
-   stub		noasync
-   unstack	noasync
-   leaveloop	noasync
-   aelem	noasync
-   aelemfast	noasync	
-   helem	noasync
-   pushre	noasync
-   subst	noasync
-   const	noasync extend=1
-   list		noasync
-   join		noasync
-   split	noasync
-   concat	noasync
-   push		noasync
-   pop  	noasync
-   shift 	noasync
-   unshift     	noasync
-   length	noasync
-   substr	noasync
-   stringify	noasync
-   eq		noasync
-   ne		noasync
-   gt		noasync
-   lt		noasync
-   ge		noasync
-   le		noasync
-   enteriter	noasync
-   ord		noasync
+our @ops;
+our $insn;
+our $op;
+our $op_name;
+our @op_loop;
+our %op_regcomp;
+
+# ops that cause immediate return to the interpreter
+my %f_unsafe = map +($_ => undef), qw(
+   leavesub leavesublv return
+   goto last redo next
+   eval flip leaveeval entertry
+   formline grepstart mapstart
+   substcont entereval require
+);
 
-   iter		async
-EOF
-   my (undef, $op, @flags) = split /\s+/;
+# ops with known stack extend behaviour
+# the values given are maximum values
+my %extend = (
+  pushmark  => 0,
+  nextstate => 0, # might reduce the stack
+  unstack   => 0,
+  enter     => 0,
+
+  stringify => 0,
+  not       => 0,
+  and       => 0,
+  or        => 0,
+  gvsv      => 0,
+  rv2gv     => 0,
+  preinc    => 0,
+  predec    => 0,
+  postinc   => 0,
+  postdec   => 0,
+  aelem     => 0,
+  helem     => 0,
+  qr        => 1, #???
+  pushre    => 1,
+  gv        => 1,
+  aelemfast => 1,
+  aelem     => 0,
+  padsv     => 1,
+  const	    => 1,
+  pop       => 1,
+  shift     => 1,
+  eq        => -1,
+  ne        => -1,
+  gt        => -1,
+  lt        => -1,
+  ge        => -1,
+  lt        => -1,
+  cond_expr => -1,
+  add       => -1,
+  subtract  => -1,
+  multiply  => -1,
+  divide    => -1,
+  aassign   => 0,
+  sassign   => -2,
+  method    => 0,
+  method_named => 1,
+);
 
-   undef $flag{$_}{$op}
-      for ("known", @flags);
-}
+# ops that do not need an ASYNC_CHECK
+my %f_noasync = map +($_ => undef), qw(
+   mapstart grepstart match entereval
+   enteriter entersub leaveloop
+
+   pushmark nextstate caller
+
+   const stub unstack
+   last next redo goto seq
+   padsv padav padhv padany
+   aassign sassign orassign
+   rv2av rv2cv rv2gv rv2hv refgen
+   gv gvsv
+   add subtract multiply divide
+   complement cond_expr and or not
+   bit_and bit_or bit_xor
+   defined
+   method method_named bless
+   preinc postinc predec postdec
+   aelem aelemfast helem delete exists
+   pushre subst list lslice join split concat
+   length substr stringify ord
+   push pop shift unshift
+   eq ne gt lt ge le
+   regcomp regcreset regcmaybe
+);
 
 my %callop = (
-   entersub => "(PL_ppaddr [OP_ENTERSUB]) (aTHX)",
+   entersub => "(PL_op->op_ppaddr) (aTHX)",
    mapstart => "Perl_pp_grepstart (aTHX)",
 );
 
@@ -159,7 +197,14 @@
    $source .= "  PL_op = nextop; nextop = " . (callop $op) . ";\n";
 }
 
+sub out_cond_jump {
+   $source .= "  if (nextop == (OP *)${$_[0]}L) goto op_${$_[0]};\n";
+}
+
 sub out_jump_next {
+   out_cond_jump $op_regcomp{$$op}
+      if $op_regcomp{$$op};
+
    assert "nextop == (OP *)${$op->next}";
    $source .= "  goto op_${$op->next};\n";
 }
@@ -175,10 +220,6 @@
    out_jump_next;
 }
 
-sub out_cond_jump {
-   $source .= "  if (nextop == (OP *)${$_[0]}L) goto op_${$_[0]};\n";
-}
-
 sub op_entersub {
    out_callop;
    $source .= "  RUNOPS_TILL ((OP *)${$op->next}L);\n";
@@ -196,16 +237,18 @@
 }
 
 sub op_pushmark {
-   $source .= "  PUSHMARK (PL_stack_sp);\n";
+   $source .= "  faster_PUSHMARK (PL_stack_sp);\n";
 
    out_next;
 }
 
-if (0 && $Config{useithreads} ne "define") {
+if ($Config{useithreads} ne "define") {
    # disable optimisations on ithreads
 
    *op_const = sub {
-      $source .= "  { dSP; XPUSHs ((SV *)${$op->sv}L); PUTBACK; }\n";
+      $source .= "  { dSP; PUSHs ((SV *)${$op->sv}L); PUTBACK; }\n";
+
+      $ops[0]{follows_const}++ if @ops;#d#
 
       out_next;
    };
@@ -235,7 +278,7 @@
       }
 
       $source .= "    dSP;\n";
-      $source .= "    XPUSHs (sv);\n";
+      $source .= "    PUSHs (sv);\n";
       $source .= "    PUTBACK;\n";
       $source .= "  }\n";
 
@@ -245,7 +288,6 @@
    *op_gvsv = sub {
       $source .= "  {\n";
       $source .= "    dSP;\n";
-      $source .= "    EXTEND (SP, 1);\n";
 
       if ($op->private & B::OPpLVAL_INTRO) {
         $source .= "    PUSHs (save_scalar ((GV *)${$op->sv}L));\n";
@@ -315,36 +357,86 @@
 
 sub op_padsv {
    my $flags = $op->flags;
-   my $target = $op->targ;
+   my $padofs = "(PADOFFSET)" . $op->targ;
 
    $source .= <<EOF;
   {
     dSP;
-    XPUSHs (PAD_SV ((PADOFFSET)$target));
+    SV *sv = PAD_SVl ($padofs);
+EOF
+
+   if (($flags & B::OPf_MOD) && ($op->private & B::OPpLVAL_INTRO)) {
+      $source .= "    SAVECLEARSV (PAD_SVl ($padofs));\n";
+      $ops[0]{follows_padsv_lval_intro}++ if @ops;#d#
+   }
+         
+   $source .= <<EOF;
+    PUSHs (sv);
     PUTBACK;
 EOF
-   if ($op->flags & B::OPf_MOD) {
-      if ($op->private & B::OPpLVAL_INTRO) {
-         $source .= "    SAVECLEARSV (PAD_SVl ((PADOFFSET)$target));\n";
-      } elsif ($op->private & B::OPpDEREF) {
-         my $deref = $op->private & B::OPpDEREF;
-         $source .= "    Perl_vivify_ref (PAD_SVl ((PADOFFSET)$target), $deref);\n";
-      }
+
+   if (($flags & B::OPf_MOD) && ($op->private & B::OPpDEREF)) {
+      $source .= "    if (!SvROK (sv)) vivify_ref (sv, " . $op->private . " & OPpDEREF);\n";
    }
+   $source .= "  }\n";
+
+   out_next;
+}
+
+sub op_sassign {
+  $source .= <<EOF;
+  {
+    dSP;
+    dPOPTOPssrl;
+EOF
+   $source .= "    SV *temp = left; left = right; right = temp;\n"
+      if $op->private & B::OPpASSIGN_BACKWARDS;
+
+   if ($insn->{follows_padsv_lval_intro} && !($op->private & B::OPpASSIGN_BACKWARDS)) {
+      # simple assignment - the target exists, but is basically undef
+      $source .= "    SvSetSV (right, left);\n";
+   } else {
+      $source .= "    SvSetMagicSV (right, left);\n";
+   }
+
    $source .= <<EOF;
+    SETs (right);
+    PUTBACK;
   }
 EOF
 
-   out_next;
+  out_next;
 }
 
 # pattern const+ (or general push1)
-# pattern pushmark return(?)
 # pattern pushmark gv rv2av pushmark padsv+o.ä. aassign
 
-# pattern const method_named
 sub op_method_named {
-   $source .= <<EOF;
+   if ($insn->{follows_const}) {
+      $source .= <<EOF;
+  {
+    dSP;
+    static SV *last_cv;
+    static U32 last_sub_generation;
+
+    /* simple "polymorphic" inline cache */
+    if (PL_sub_generation == last_sub_generation)
+      {
+        PUSHs (last_cv);
+        PUTBACK;
+      }
+    else
+      {
+        PL_op = nextop; nextop = Perl_pp_method_named (aTHX);
+
+        SPAGAIN;
+        last_sub_generation = PL_sub_generation;
+        last_cv             = TOPs;
+      }
+  }
+EOF
+   } else {
+      $source .= <<EOF;
   {
     static HV *last_stash;
     static SV *last_cv;
@@ -361,7 +453,7 @@
         if (stash == last_stash
             && PL_sub_generation == last_sub_generation)
           {
-            XPUSHs (last_cv);
+            PUSHs (last_cv);
             PUTBACK;
           }
         else
@@ -381,13 +473,15 @@
       }
   }
 EOF
+   }
 
    out_next;
 }
 
 sub op_grepstart {
    out_callop;
-   out_cond_jump $op->next->other;
+   $op = $op->next;
+   out_cond_jump $op->other;
    out_jump_next;
 }
 
@@ -406,7 +500,7 @@
    out_callop;
 
    out_cond_jump $_->[$idx]
-      for reverse @loop;
+      for reverse @op_loop;
 
    $source .= "  return nextop;\n";
 }
@@ -426,65 +520,130 @@
 sub cv2c {
    my ($cv) = @_;
 
-   @loop = ();
+   local @ops;
+   local @op_loop;
+   local %op_regcomp;
 
    my %opsseen;
    my @todo = $cv->START;
+   my %op_target;
+   my $numpushmark;
 
    while (my $op = shift @todo) {
       for (; $$op; $op = $op->next) {
          last if $opsseen{$$op}++;
-         push @ops, $op;
 
          my $name = $op->name;
          my $class = B::class $op;
 
+         my $insn = { op => $op };
+
+         push @ops, $insn;
+
+         if (exists $extend{$name}) {
+            my $extend = $extend{$name};
+            $extend = $extend->($op) if ref $extend;
+            $insn->{extend} = $extend if defined $extend;
+         }
+
+         push @todo, $op->next;
+
          if ($class eq "LOGOP") {
-            unshift @todo, $op->other; # unshift vs. push saves jumps
+            push @todo, $op->other;
+            $op_target{${$op->other}}++;
+
+            # regcomp/o patches ops at runtime, lets expect that
+            if ($name eq "regcomp" && $op->other->pmflags & B::PMf_KEEP) {
+               $op_target{${$op->first}}++;
+               $op_regcomp{${$op->first}} = $op->next;
+            }
+
          } elsif ($class eq "PMOP") {
-            unshift @todo, $op->pmreplstart if ${$op->pmreplstart};
+            if (${$op->pmreplstart}) {
+               unshift @todo, $op->pmreplstart;
+               $op_target{${$op->pmreplstart}}++;
+            }
+
          } elsif ($class eq "LOOP") {
-            push @loop, [$op->nextop, $op->lastop->next, $op->redoop->next];
+            my @targ = ($op->nextop, $op->lastop->next, $op->redoop->next);
+
+            push @op_loop, \@targ;
+            push @todo, @targ;
+
+            $op_target{$$_}++ for @targ;
+
+         } elsif ($class eq "COP") {
+            $insn->{bblock}++ if defined $op->label;
+
+         } else {
+            if ($name eq "pushmark") {
+               $numpushmark++;
+            }
          }
       }
    }
 
+   $_->{bblock}++ for grep $op_target{${$_->{op}}}, @ops;
+
    local $source = <<EOF;
 OP *%%%FUNC%%% (pTHX)
 {
-  register OP *nextop = (OP *)${$ops[0]}L;
+  register OP *nextop = (OP *)${$ops[0]->{op}}L;
 EOF
 
+   $source .= "  faster_PUSHMARK_PREALLOC ($numpushmark);\n"
+      if $numpushmark;
+
    while (@ops) {
-      $op = shift @ops;
+      $insn = shift @ops;
+
+      $op = $insn->{op};
       $op_name = $op->name;
 
+      my $class = B::class $op;
+
+      $source .= "\n/* start basic block */\n" if exists $insn->{bblock};#d#
       $source .= "op_$$op: /* $op_name */\n";
       #$source .= "fprintf (stderr, \"$$op in op $op_name\\n\");\n";#d#
       #$source .= "{ dSP; sv_dump (TOPs); }\n";#d#
 
       $source .= "  PERL_ASYNC_CHECK ();\n"
-         unless exists $flag{noasync}{$op_name};
+         unless exists $f_noasync{$op_name};
 
       if (my $can = __PACKAGE__->can ("op_$op_name")) {
          # handcrafted replacement
+
+         if ($insn->{extend} > 0) {
+            # coalesce EXTENDs
+            # TODO: properly take negative preceeding and following EXTENDs into account
+            for my $i (@ops) {
+               last if exists $i->{bblock};
+               last unless exists $i->{extend};
+               my $extend = delete $i->{extend};
+               $insn->{extend} += $extend if $extend > 0;
+            }
+
+            $source .= "  { dSP; EXTEND (SP, $insn->{extend}); PUTBACK; }\n"
+               if $insn->{extend} > 0;
+         }
+
          $can->($op);
 
-      } elsif (exists $flag{unsafe}{$op_name}) {
+      } elsif (exists $f_unsafe{$op_name}) {
          # unsafe, return to interpreter
          assert "nextop == (OP *)$$op";
          $source .= "  return nextop;\n";
 
-      } elsif ("LOGOP" eq B::class $op) {
-         # logical operation with optionaö branch
+      } elsif ("LOGOP" eq $class) {
+         # logical operation with optional branch
          out_callop;
          out_cond_jump $op->other;
          out_jump_next;
 
-      } elsif ("PMOP" eq B::class $op) {
+      } elsif ("PMOP" eq $class) {
          # regex-thingy
          out_callop;
-         out_cond_jump $op->pmreplroot if ${$op->pmreplroot};
+         out_cond_jump $op->pmreplroot if $op_name ne "pushre" && ${$op->pmreplroot};
          out_jump_next;
 
       } else {
@@ -505,18 +664,38 @@
    $source
 }
 
-sub source2ptr {
-   my ($source) = @_;
+my $uid = "aaaaaaa0";
+my %so;
 
-   my $md5 = Digest::MD5::md5_hex $source;
-   $source =~ s/%%%FUNC%%%/Faster_$md5/;
+sub func2ptr {
+   my (@func) = @_;
 
-   my $stem = "/tmp/$md5";
+   #LOCK
+   mkdir $CACHEDIR, 0777;
+   sysopen my $meta_fh, "$CACHEDIR/meta", &Fcntl::O_RDWR | &Fcntl::O_CREAT, 0666
+      or die "$$CACHEDIR/meta: $!";
+   binmode $meta_fh, ":raw:perlio";
+   fcntl_lock fileno $meta_fh
+      or die "$CACHEDIR/meta: $!";
+
+   my $meta = eval { Storable::fd_retrieve $meta_fh } || { version => 1 };
+
+   for my $f (@func) {
+      $f->{func} = "F" . Digest::MD5::md5_hex ($f->{source});
+      $f->{so}   = $meta->{$f->{func}};
+   }
+
+   if (grep !$_->{so}, @func) {
+      my $stem;
+      
+      do {
+         $stem = "$CACHEDIR/$$-" . $uid++;
+      } while -e "$stem$_so";
 
-   unless (-e "$stem$_so") {
-      open FILE, ">:raw", "$stem.c";
-      print FILE <<EOF;
+      open my $fh, ">:raw", "$stem.c";
+      print $fh <<EOF;
 #define PERL_NO_GET_CONTEXT
+#define PERL_CORE
 
 #include <assert.h>
 
@@ -524,6 +703,14 @@
 #include "perl.h"
 #include "XSUB.h"
 
+#if 1
+# define faster_PUSHMARK_PREALLOC(count) while (PL_markstack_ptr + (count) >= PL_markstack_max) markstack_grow ()
+# define faster_PUSHMARK(p) *++PL_markstack_ptr = (p) - PL_stack_base
+#else
+# define faster_PUSHMARK_PREALLOC(count) 1
+# define faster_PUSHMARK(p) PUSHMARK(p)
+#endif
+
 #define RUNOPS_TILL(op)						\\
   while (nextop != (op))					\\
     {								\\
@@ -532,37 +719,94 @@
     }
 
 EOF
-      print FILE $source;
-      close FILE;
+      for my $f (grep !$_->{so}, @func) {
+         next if $f->{so} = $meta->{$f->{func}}; # some cv's alias others
+
+         warn "compiling $f->{name} to $stem$_so:$f->{func}\n" if $verbose > 1;
+         my $source = $f->{source};
+         $source =~ s/%%%FUNC%%%/$f->{func}/g;
+         print $fh $source;
+         $meta->{$f->{func}} = $f->{so} = $stem;
+      }
+
+      close $fh;
       system "$COMPILE -o $stem$_o $stem.c";
+      unlink "$stem.c" unless $ENV{FASTER_DEBUG} > 0;
       system "$LINK -o $stem$_so $stem$_o $LIBS";
+      unlink "$stem$_o";
    }
 
-#   warn $source;
-   my $so = DynaLoader::dl_load_file "$stem$_so"
-      or die "$stem$_so: $!";
+   for my $f (@func) {
+      my $stem = $f->{so};
+
+      my $so = ($so{$stem} ||= DynaLoader::dl_load_file "$stem$_so")
+         or die "$stem$_so: $!";
 
-   DynaLoader::dl_find_symbol $so, "Faster_$md5"
-      or die "Faster_$md5: $!"
+      #unlink "$stem$_so";
+
+      $f->{ptr} = DynaLoader::dl_find_symbol $so, $f->{func}
+         or die "$f->{func} not found in $stem$_so: $!";
+   }
+
+   seek $meta_fh, 0,  0 or die "$CACHEDIR/meta: $!";
+   Storable::nstore_fd $meta, $meta_fh;
+   truncate $meta_fh, tell $meta_fh;
+
+   # UNLOCK (by closing $meta_fh)
 }
 
+my %ignore;
+
 sub entersub {
    my ($cv) = @_;
 
-   # always compile the whole stash
-#   my @stash = $cv->STASH->ARRAY;
-#   warn join ":", @stash;
-#   exit;
+   my $pkg = $cv->STASH->NAME;
+
+   return if $ignore{$pkg};
+
+   warn "optimising ", $cv->STASH->NAME, "\n"
+      if $verbose;
 
    eval {
-      my $source = cv2c $cv;
+      my @func;
 
-      my $ptr = source2ptr $source;
+      push @func, {
+         cv     => $cv,
+         name   => "<>",
+         source => cv2c $cv,
+      };
+
+      # always compile the whole stash
+      my %stash = $cv->STASH->ARRAY;
+      while (my ($k, $v) = each %stash) {
+         $v->isa (B::GV::)
+            or next;
+
+         my $cv = $v->CV;
+
+         if ($cv->isa (B::CV::)
+             && ${$cv->START}
+             && $cv->START->name ne "null") {
+
+            push @func, {
+               cv     => $cv,
+               name   => $k,
+               source => cv2c $cv,
+            };
+         }
+      }
 
-      patch_cv $cv, $ptr;
+      func2ptr @func;
+
+      for my $f (@func) {
+         patch_cv $f->{cv}, $f->{ptr};
+      }
    };
 
-   warn $@ if $@;
+   if ($@) {
+      $ignore{$pkg}++;
+      warn $@;
+   }
 }
 
 hook_entersub;
@@ -571,6 +815,36 @@
 
 =back
 
+=head1 ENVIRONMENT VARIABLES
+
+The following environment variables influence the behaviour of Faster:
+
+=over 4
+
+=item FASTER_VERBOSE
+
+Faster will output more informational messages when set to values higher
+than C<0>. Currently, C<1> outputs which packages are being compiled, C<3>
+outputs the cache directory and C<10> outputs information on which perl
+function is compiled into which shared object.
+
+=item FASTER_DEBUG
+
+Add debugging code when set to values higher than C<0>. Currently, this
+adds 1-3 C<assert>'s per perl op (FASTER_DEBUG > 1), to ensure that opcode
+order and C execution order are compatible.
+
+=item FASTER_CACHE
+
+Set a persistent cache directory that caches compiled code fragments. The
+default is C<$HOME/.perl-faster-cache> if C<HOME> is set and a temporary
+directory otherwise.
+
+This directory will always grow in size, so you might need to erase it
+from time to time.
+
+=back
+
 =head1 BUGS/LIMITATIONS
 
 Perl will check much less often for asynchronous signals in
@@ -578,24 +852,24 @@
 iteration and every I/O operator, though.
 
 The following things will disable Faster. If you manage to enable them at
-runtime, bad things will happen.
+runtime, bad things will happen. Enabling them at startup will be fine,
+though.
 
  enabled tainting
  enabled debugging
 
-This will dramatically reduce Faster's performance:
+Thread-enabled builds of perl will dramatically reduce Faster's
+performance, but you don't care about speed if you enable threads anyway.
 
- threads (but you don't care about speed if you use threads anyway)
+These constructs will force the use of the interpreter for the currently
+executed function as soon as they are being encountered during execution.
 
-These constructs will force the use of the interpreter as soon as they are
-being executed, for the rest of the currently executed:
-
- .., ... (flipflop operators)
  goto
  next, redo (but not well-behaved last's)
  eval
  require
  any use of formats
+ .., ... (flipflop operators)
 
 =head1 AUTHOR