Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
B::CC(3)	      User Contributed Perl Documentation	      B::CC(3)

NAME
       B::CC - Perl compiler's optimized C translation backend

SYNOPSIS
	       perl -MO=CC[,OPTIONS] foo.pl

DESCRIPTION
       This compiler backend takes Perl	source and generates C source code
       corresponding to	the flow of your program with unrolled ops and
       optimised stack handling	and lexicals variable types. In	other words,
       this backend is somewhat	a "real" compiler in the sense that many
       people think about compilers. Note however that,	currently, it is a
       very poor compiler in that although it generates	(mostly, or at least
       sometimes) correct code,	it performs relatively few optimisations.
       This will change	as the compiler	and the	types develops.	The result is
       that running an executable compiled with	this backend may start up more
       quickly than running the	original Perl program (a feature shared	by the
       C compiler backend--see B::C) and may also execute slightly faster.
       This is by no means a good optimising compiler--yet.

OPTIONS
       If there	are any	non-option arguments, they are taken to	be names of
       objects to be saved (probably doesn't work properly yet).  Without
       extra arguments,	it saves the main program.

       -ofilename
	   Output to filename instead of STDOUT

       -c  Check and abort.

	   Compiles and	prints only warnings, but does not emit	C code.

       -v  Verbose compilation (prints a few compilation stages).

       --  Force end of	options

       -uPackname
	   Force apparently unused subs	from package Packname to be compiled.
	   This	allows programs	to use eval "foo()" even when sub foo is never
	   seen	to be used at compile time. The	down side is that any subs
	   which really	are never used also have code generated. This option
	   is necessary, for example, if you have a signal handler foo which
	   you initialise with "$SIG{BAR} = "foo"".  A better fix, though, is
	   just	to change it to	"$SIG{BAR} = \&foo". You can have multiple -u
	   options. The	compiler tries to figure out which packages may
	   possibly have subs in which need compiling but the current version
	   doesn't do it very well. In particular, it is confused by nested
	   packages (i.e.  of the form "A::B") where package "A" does not
	   contain any subs.

       -UPackname  "unuse" skip	Package
	   Ignore all subs from	Package	to be compiled.

	   Certain packages might not be needed	at run-time, even if the
	   pessimistic walker detects it.

       -mModulename
	   Instead of generating source	for a runnable executable, generate
	   source for an XSUB module. The boot_Modulename function (which
	   DynaLoader can look for) does the appropriate initialisation	and
	   runs	the main part of the Perl source that is being compiled.

       -nInitname
	   Provide a different init name for additional	objects	added via
	   cmdline.

       -strict
	   With	a DEBUGGING perl compile-time errors for range and flip
	   without compile-time	context	are only warnings.  With "-strict"
	   these warnings are fatal, otherwise only run-time errors occur.

       -On Optimisation	level (n = 0, 1, 2). -O	means -O1.

	   The following B::C optimisations are	applied	automatically:

	   optimize_warn_sv save_data_fh av-init2|av_init save_sig destruct
	   pv_copy_on_grow

	   -O1 sets -ffreetmps-each-bblock.

	   -O2 adds -ffreetmps-each-loop, "-faelem" and	-fno-destruct from
	   B::C.

	   The following options must be set explicitly:

	     B<-fno-taint> or B<-fomit-taint>,

	     B<-fslow-signals>,

	     B<-no-autovivify>,

	     B<-fno-magic>.

       -f"OPTIM"
	   Force optimisations on or off one at	a time.	 Unknown optimizations
	   are passed down to B::C.

       -ffreetmps-each-bblock
	   Delays FREETMPS from	the end	of each	statement to the end of	the
	   each	basic block.

	   Enabled with	-O1.

       -ffreetmps-each-loop
	   Delays FREETMPS from	the end	of each	statement to the end of	the
	   group of basic blocks forming a loop. At most one of	the
	   freetmps-each-* options can be used.

	   Enabled with	-O2.

       -faelem
	   Enable array	element	access optimizations, allowing unchecked fast
	   access under	certain	circumstances.

	   Enabled with	-O2 and	not-threaded perls only.

       -fno-inline-ops
	   Do not inline calls to certain small	pp ops.

	   Most	of the inlinable ops were already inlined.  Turns off inlining
	   for some new	ops.

	   AUTOMATICALLY inlined:

	   pp_null pp_stub pp_unstack pp_and pp_andassign pp_or	pp_orassign
	   pp_cond_expr	pp_padsv pp_const pp_nextstate pp_dbstate pp_rv2gv
	   pp_sort pp_gv pp_gvsv pp_aelemfast pp_ncmp pp_add pp_subtract
	   pp_multiply pp_divide pp_modulo pp_left_shift pp_right_shift
	   pp_i_add pp_i_subtract pp_i_multiply	pp_i_divide pp_i_modulo	pp_eq
	   pp_ne pp_lt pp_gt pp_le pp_ge pp_i_eq pp_i_ne pp_i_lt pp_i_gt
	   pp_i_le pp_i_ge pp_scmp pp_slt pp_sgt pp_sle	pp_sge pp_seq pp_sne
	   pp_sassign pp_preinc	pp_pushmark pp_list pp_entersub	pp_formline
	   pp_goto pp_enterwrite pp_leavesub pp_leavewrite pp_entergiven
	   pp_leavegiven pp_entereval pp_dofile	pp_require pp_entertry
	   pp_leavetry pp_grepstart pp_mapstart	pp_grepwhile pp_mapwhile
	   pp_return pp_range pp_flip pp_flop pp_enterloop pp_enteriter
	   pp_leaveloop	pp_next	pp_redo	pp_last	pp_subst pp_substcont

	   DONE	with -finline-ops:

	   pp_enter pp_reset pp_regcreset pp_stringify

	   TODO	with -finline-ops:

	   pp_anoncode pp_wantarray pp_srefgen pp_refgen pp_ref	pp_trans
	   pp_schop pp_chop pp_schomp pp_chomp pp_not pp_sprintf pp_anonlist
	   pp_shift pp_once pp_lock pp_rcatline	pp_close pp_time pp_alarm
	   pp_av2arylen: no lvalue, pp_length: no magic

       -fomit-taint
	   Omits generating code for handling perl's tainting mechanism.

       -fslow-signals
	   Add PERL_ASYNC_CHECK	after every op as in the old Perl runloop
	   before 5.13.

	   perl	"Safe signals" check the state of incoming signals after every
	   op.	See
	   <http://perldoc.perl.org/perlipc.html#Deferred-Signals-(Safe-Signals)>
	   We trade safety for more speed and delay the	execution of non-IO
	   signals (IO signals are already handled in PerlIO) from after every
	   single Perl op to the same ops as used in 5.14.

	   Only	with -fslow-signals we get the old slow	and safe behaviour.

       -fno-name-magic
	   With	the default "-fname-magic" we infer the	SCALAR type for
	   specially named locals vars and most	ops use	C vars then, not the
	   perl	vars.  Arithmetic and comparison is inlined. Scalar magic is
	   bypassed.

	   With	"-fno-name-magic" do not infer a local variable	type from its
	   name:

	     B<_i> suffix for int, B<_d> for double/num, B<_ir>	for register int

	   See the experimental	"-ftype-attr" type attributes.	Currently
	   supported are int and num only. See </load_pad>.

       -ftype-attr (DOES NOT WORK YET)
	   Experimentally support type attributes for int and num, SCALAR only
	   so far.  For	most ops new C vars are	used then, not the fat perl
	   vars.  Very awkward to use until the	basic type classes are
	   supported from within core or use types.

	   Enabled with	-O2. See TYPES and </load_pad>.

       -fno-autovivify
	   Do not vivify array and soon	also hash elements when	accessing
	   them.  Beware: Vivified elements default to undef, unvivified
	   elements are	invalid.

	   This	is the same as the pragma "no autovivification"	and allows
	   very	fast array accesses, 4-6 times faster, without the overhead of
	   autovivification.

       -fno-magic
	   Assume certain data being optimized is never	tied or	is holding
	   other magic.	 This mainly holds for arrays being optimized, but in
	   the future hashes also.

       -D  Debug options (concatenated or separate flags like "perl -D").
	   Verbose debugging options are crucial, because the interactive
	   debugger Od adds a lot of ballast to	the resulting code.

       -Dr Writes debugging output to STDERR just as it's about	to write to
	   the program's runtime (otherwise writes debugging info as comments
	   in its C output).

       -DO Outputs each	OP as it's compiled

       -DT Outputs the contents	of the stack at	each OP.  Values are
	   B::Stackobj objects.

       -Dc Outputs the contents	of the loop context stack, the @cxstack.

       -Dw Outputs the contents	of the shadow stack at each OP.

       -Da Outputs the contents	of the shadow pad of lexicals as it's loaded
	   for each sub	or the main program.

       -Dq Outputs the name of each fake PP function in	the queue as it's
	   about to process it.

       -Dl Output the filename and line	number of each original	line of	Perl
	   code	as it's	processed ("pp_nextstate").

       -Dt Outputs timing information of compilation stages.

       -DF Add Flags info to the code.

NOTABLE	FUNCTIONS
   cc_queue
       Creates a new ccpp optree.

       Initialised by saveoptree_callback in B::C, replaces
       B::C::walk_and_save_optree.  Called by every "CV::save" if ROOT.
       blocksort also creates its block	closure	with cc_queue.

save_or_restore_lexical_state
       The compiler tracks state of lexical variables in @pad to generate
       optimised code. But multiple execution paths lead to the	entry point of
       a basic block.  The state of the	first execution	path is	saved and all
       other execution paths are restored to the state of the first one.

       Missing flags are regenerated by	loading	values.

       Added flags must	are removed; otherwise the compiler would be too
       optimistic, hence generating code which doesn't match state of the
       other execution paths.

   load_pad
       Load pad	takes (the elements of)	a PADLIST as arguments and loads up
       @pad with Stackobj-derived objects which	represent those	lexicals.

       If/when perl itself can generate	type information "(my int $foo;	my
       $foo : int)" then we'll take advantage of that here. Until then,	we'll
       use the "-fno-name-magic" in -fname-magic hack to tell the compiler
       when we want a lexical to be a particular type or to be a register.

   label
       We not only mark	named labels in	C as such - with prefix	"label_".

       We also have to mark each known (back jumps) and	yet unknown branch
       targets (forward	jumps) for compile-time	generated branch points, with
       the "lab_" prefix.

EXAMPLES
	       perl -MO=CC,-O2,-ofoo.c foo.pl
	       perl cc_harness -o foo foo.c

       Note that "cc_harness" lives in the "B" subdirectory of your perl
       library directory. The utility called "perlcc" may also be used to help
       make use	of this	compiler.

	       # create	a shared XS module
	       perl -MO=CC,-mFoo,-oFoo.c Foo.pm
	       perl cc_harness -shared -c -o Foo.so Foo.c

	       # side-effects just for the types and attributes
	       perl -MB::CC -e'my int $i:unsigned; ...'

TYPES
       Implemented type	classes	are int	and num.  Planned is str also.
       Implemented are only SCALAR types yet.  Typed arrays and	hashes and
       perfect hashes need coretypes, types and	proper "const" support first.

       Deprecated are inferred types via the names of locals, with '_i', '_d'
       suffix and an optional 'r' suffix for register allocation.

	 C<my ($i_i, $j_ir, $num_d);>

       Planned type attributes are int,	num, str, unsigned, ro / const.

       The attributes are perl attributes, and "int|num|str" are either
       compiler	classes	or hints for more allowed types.

	 C<my int $i :num;>  declares a	NV with	SVf_IOK. Same as C<my $i:int:double;>
	 C<my int $i;>		declares an IV.	Same as	C<my $i:int;>
	 C<my int $i :str;>  declares a	PVIV. Same as C<my $i:int:string;>

	 C<my int @array :unsigned = (0..4);> will be used as c	var in faster arithmetic and cmp.
					      With :const or :ro even more.
	 C<my str %hash	:const
	   = (foo => 'foo', bar	=> 'bar');> declare string values,
					    generate as	read-only perfect hash.

       :unsigned is valid for int only and declares an UV.

       :register denotes optionally a short and	hot life-time.

       :temporary are usually generated	internally, nameless lexicals.	They
       are more	aggressivly destroyed and ignored.

       :ro or :const throw a compile-time error	on write access	and may
       optimize	the internal structure of the variable.	We don't need to write
       back the	variable to perl (lexical write_back).

       STATUS

       OK (classes only):

	 my int	$i;
	 my num	$d;

       NOT YET OK (attributes):

	 my int	$i :register;
	 my $i :int;
	 my $const :int:const;
	 my $uv	:int:unsigned;

       ISSUES

       This does not work with pure perl, unless you "use B::CC" or "use
       types" or implement the classes and attribute type stubs	in your	code,
       "sub Mypkg::MODIFY_SCALAR_ATTRIBUTES {}"	and "sub
       Mypkg::FETCH_SCALAR_ATTRIBUTES {}".  (TODO: empty should	be enough to
       be detected by the compiler.)

       Compiled	code pulls in the magic	MODIFY_SCALAR_ATTRIBUTES and
       FETCH_SCALAR_ATTRIBUTES functions, even if they are used	at compile
       time only.

       Using attributes	adds an	import block to	your code.

       Up until	5.20 only our variable attributes are checked at compile-time,
       my variables attributes at run-time only, which is too late for the
       compiler.  Perl attributes need to be fixed for types hints by adding
       "CHECK_SCALAR_ATTRIBUTES".

       FUTURE

       We should be able to support types on ARRAY and HASH.  For arrays also
       sizes to	omit bounds-checking.

	 my int	@array;	# array	of ints, faster	magic-less access esp. in inlined arithmetic and cmp.
	 my str	@array : const = qw(foo	bar);	# compile-time error on	write. no lexical write_back

	 my int	$hash =	{"1" =>	1, "2" => 2};	# int values, type-checked on write my
	 str %hash1 : const = (foo => 'bar');	# string keys only => maybe gperf
						# compile-time error on	write

       Typed hash keys are always strings, as array keys are always int. Only
       the values are typed.

       We should be also able to add type attributes for functions and
       methods,	i.e. for argument and return types. See	types and
       <http://blogs.perl.org/users/rurban/2011/02/use-types.html>

BUGS
       Plenty. Current status: experimental.

DIFFERENCES
       These aren't really bugs	but they are constructs	which are heavily tied
       to perl's compile-and-go	implementation and with	which this compiler
       backend cannot cope.

   Loops
       Standard	perl calculates	the target of "next", "last", and "redo" at
       run-time. The compiler calculates the targets at	compile-time.  For
       example,	the program

	   sub skip_on_odd { next NUMBER if $_[0] % 2 }
	   NUMBER: for ($i = 0;	$i < 5;	$i++) {
	       skip_on_odd($i);
	       print $i;
	   }

       produces	the output

	   024

       with standard perl but calculates with the compiler the goto
       label_NUMBER wrong, producing 01234.

   Context of ".."
       The context (scalar or array) of	the ".." operator determines whether
       it behaves as a range or	a flip/flop. Standard perl delays until
       runtime the decision of which context it	is in but the compiler needs
       to know the context at compile-time. For	example,

	   @a =	(4,6,1,0,0,1);
	   sub range { (shift @a)..(shift @a) }
	   print range();
	   while (@a) {	print scalar(range()) }

       generates the output

	   456123E0

       with standard Perl but gives a run-time warning with compiled Perl.

       If the option -strict is	used it	gives a	compile-time error.

   Arithmetic
       Compiled	Perl programs use native C arithmetic much more	frequently
       than standard perl. Operations on large numbers or on boundary cases
       may produce different behaviour.	 In doubt B::CC	code behaves more like
       with "use integer".

   Deprecated features
       Features	of standard perl such as $[ which have been deprecated in
       standard	perl since Perl5 was released have not been implemented	in the
       optimizing compiler.

AUTHORS
       Malcolm Beattie "MICB at	cpan.org" (1996-1998, retired),	Vishal Bhatia
       <vishal at deja.com> I(1999), Gurusamy Sarathy <gsar at cpan.org>
       I(1998-2001), Reini Urban "perl-compiler	at googlegroups.com"
       I(2008-now), Heinz Knutzen "heinz.knutzen at gmx.de" I(2010) Will
       Braswell	"wbraswell at hush.com"	I(2012)

perl v5.32.1			  2019-05-07			      B::CC(3)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTABLE FUNCTIONS | save_or_restore_lexical_state | EXAMPLES | TYPES | BUGS | DIFFERENCES | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=B::CC&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help