File Coverage

blib/lib/GCC/Builtins.pm

Criterion	Covered	Total	%
statement	8	8	100.0
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	11	11	100.0

package GCC::Builtins;

use 5.006;
use strict;
use warnings;

our $VERSION = '0.06';

our @ISA = (qw/Exporter DynaLoader/);
our %EXPORT_TAGS = ( 'all' => [qw( bswap16 bswap32 bswap64 clrsb clrsbl clrsbll clz clzl clzll ctz ctzl ctzll ffs ffsl ffsll huge_val huge_valf huge_vall inf infd128 infd32 infd64 inff infl nan nanf nanl parity parityl parityll popcount popcountl popcountll powi powif powil )] );
our @EXPORT_OK   = ( @{ $EXPORT_TAGS{'all'} } );

require DynaLoader;
__PACKAGE__->bootstrap($VERSION);

#########################################################################
#### WARNING: do not edit GCC/Buildins.pm or GCC/Buildins.xs
####          or typemap or t/6*.t files
####          they are auto-generated by me and all changes will be lost
####          ALSO, no need to say that the POD here is also auto-generated
####          and will be short-lived.
#### EDIT all these in file
####    sbin/build-gcc-builtins-package.pl
#### and then run sbin/build-gcc-builtins-package.pl
#### to update the auto-generated files
#########################################################################

=pod

=encoding UTF-8

=head1 NAME

GCC::Builtins - access GCC compiler builtin functions via XS

=head1 VERSION

Version 0.06

=head1 SYNOPSIS

This module provides Perl access to GCC C compiler
builtin functions.

    use GCC::Builtins qw/:all/;
    # or use GCC::Builtins qw/ ... clz ... /;
    my $leading_zeros = GCC::Builtins::clz(10);
    # 28

=head1 EXPORT

=over 2

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C<_Decimal128 infd128()>

=item * C<_Decimal32 infd32()>

=item * C<_Decimal64 infd64()>

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C

=item * C



=back

Export tag C<:all> imports B exportable functions, like:

  use GCC::Builtins qw/:all/;


=head1 SUBROUTINES

=head2 C

Returns x with the order of the bytes reversed; for example,
0xaabb becomes 0xbbaa.  Byte here always means
exactly 8 bits.


=head2 C

Similar to __builtin_bswap16, except the argument and return types
are 32-bit.


=head2 C

Similar to __builtin_bswap32, except the argument and return types
are 64-bit.


=head2 C

Returns the number of leading redundant sign bits in x, i.e. the
number of bits following the most significant bit that are identical
to it.  There are no special cases for 0 or other values.


=head2 C

Similar to __builtin_clrsb, except the argument type is
long.


=head2 C

Similar to __builtin_clrsb, except the argument type is
long long.


=head2 C

Returns the number of leading 0-bits in x, starting at the most
significant bit position.  If x is 0, the result is undefined.


=head2 C

Similar to __builtin_clz, except the argument type is
unsigned long.


=head2 C

Similar to __builtin_clz, except the argument type is
unsigned long long.


=head2 C

Returns the number of trailing 0-bits in x, starting at the least
significant bit position.  If x is 0, the result is undefined.


=head2 C

Similar to __builtin_ctz, except the argument type is
unsigned long.


=head2 C

Similar to __builtin_ctz, except the argument type is
unsigned long long.


=head2 C

Returns one plus the index of the least significant 1-bit of x, or
if x is zero, returns zero.


=head2 C

Similar to __builtin_ffs, except the argument type is
long.


=head2 C

Similar to __builtin_ffs, except the argument type is
long long.


=head2 C

Returns a positive infinity, if supported by the floating-point format,
else DBL_MAX.  This function is suitable for implementing the
ISO C macro HUGE_VAL.


=head2 C

Similar to __builtin_huge_val, except the return type is float.


=head2 C

Similar to __builtin_huge_val, except the return
type is long double.


=head2 C

Similar to __builtin_huge_val, except a warning is generated
if the target floating-point format does not support infinities.


=head2 C<_Decimal128 infd128()>

Similar to __builtin_inf, except the return type is _Decimal128.


=head2 C<_Decimal32 infd32()>

Similar to __builtin_inf, except the return type is _Decimal32.


=head2 C<_Decimal64 infd64()>

Similar to __builtin_inf, except the return type is _Decimal64.


=head2 C

Similar to __builtin_inf, except the return type is float.
This function is suitable for implementing the ISO C99 macro INFINITY.


=head2 C

Similar to __builtin_inf, except the return
type is long double.


=head2 C

This is an implementation of the ISO C99 function nan.


=head2 C

Similar to __builtin_nan, except the return type is float.


=head2 C

Similar to __builtin_nan, except the return type is long double.


=head2 C

Returns the parity of x, i.e. the number of 1-bits in x
modulo 2.


=head2 C

Similar to __builtin_parity, except the argument type is
unsigned long.


=head2 C

Similar to __builtin_parity, except the argument type is
unsigned long long.


=head2 C

Returns the number of 1-bits in x.


=head2 C

Similar to __builtin_popcount, except the argument type is
unsigned long.


=head2 C

Similar to __builtin_popcount, except the argument type is
unsigned long long.


=head2 C

Returns the first argument raised to the power of the second.  Unlike the
pow function no guarantees about precision and rounding are made.


=head2 C

Returns the first argument raised to the power of the second.  Unlike the
pow function no guarantees about precision and rounding are made.


=head2 C

Returns the first argument raised to the power of the second.  Unlike the
pow function no guarantees about precision and rounding are made.




=head1 UPDATING THE LIST OF FUNCTIONS

The list of functions was extracted from L
using the script C This script is
part of the distribution but it is not installed in the host system.
This file is HTML documenting these functions. I found it easier to parse
this file than to parse GCC header files, mainly because the latter
contain macros and typedef which I could not parse without the help of
the C pre-processor.

And so the list of provided files may not be perfect. Certainly there are some functions
missing. Simply because some functions do not make sense when called from Perl.
For example C,
C etc. Some others are missing because they
have exotic data types for function arguments and/or return
which I did not know how to implement that in Perl. Others
have reported missing symbols, perhaps they
need a higher C standard (adjusted via the C in C).

If you need another builtin function to be supported please raise
an L.
Please make sure you provide me with a way to include this function.
What C, how to C its return type and arguments. And
also provide a test script to test it (similar to those found in C directory).

An easy way to experiment is to use C (provided by L
to fetch and unpack the distribution
and then open a shell at the distribution directory:

   cpanm --look GCC::Builtins

and then

   sbin/build-gcc-builtins-package.sh
   sbin/build-gcc-builtins-package.pl
   perl Makefile.PL && make all && make test

Note that C, C
and C are auto-generated by above scripts. Do not
edit them. Edit C
instead.

=head1 ALTERNATIVES

The L section below suggests that a 100% performance gain
awaits users who prefer to call L rather than implementing
them in pure Perl.

However, you can still harvest those gains by coding critical sections in your Perl code
in assembly via L. Assembly can be run from within a C program with the
Gnu C Compiler (GCC) which offers the C functionality.

I have outlined how in this L
in this L,
over at the L Monastery.

Here is the relevant code:

    use Inline C;

    use strict;
    use warnings;

    # Assembly code via Inline::C to return the
    # 1. number of leading zeros of the input integer
    # 2. a number with only bit set where the MSSB is located
    #
    # by bliako
    # for https://perlmonks.org/?node_id=11158279
    # 21/03/2024

    my $z = 17;
    my $res = mssb($z);
    print "Leading zeros for $z : ".$res->[0]."\n";
    print "MSSB for $z : ".sprintf("%032b\n", $res->[1])."\n";
    # result:
    # Leading zeros for 17 : 27
    # MSSB for 17 : 00000000000000000000000000010000

    __END__
    __C__
    #include

    AV * mssb(int input){
        int num_leading_zeros;
        int mssb;
        asm volatile(
        /* note: lzcnt inp, out
         mov src, dst
         add what, dst
         # set bit of value in dst at zero-based bitposition:
         btsl bitposition, dst (it modifies dst)
        */
        "lzcnt %[input], %[num_leading_zeros]  \n\t\
         mov $32, %%eax                        \n\t\
         sub %[num_leading_zeros], %%eax       \n\t\
         sub $1, %%eax                         \n\t\
         xor %[mssb], %[mssb]                  \n\t\
         bts %%eax, %[mssb]                    \n\t\
        "
        /* outputs */
         : [num_leading_zeros] "=r" (num_leading_zeros)
         , [mssb] "=r" (mssb)
        /* inputs */
         : [input] "mr"  (input)
        /* clobbers: we are messing with these registers: */
         : "eax"
        );

        // return an arrayref of the two outputs
        AV* ret = newAV();
        sv_2mortal((SV*)ret);
        av_push(ret, newSViv(num_leading_zeros));
        av_push(ret, newSViv(mssb));

        return ret;
    }

You can also inline assembly in your Perl code with L

Be advised that GCC builtins are also calling assembly code.
In fact the above assembly code is how GCC implements C.
So, inline assembly and L should yield, more-or-less,
the same performance gain.

=head1 TESTING

For each exported sub there is a corresponding auto-generated
test file. The test goes as far as loading the library and
calling the function from Perl.

However, there may be errors in the expected results
because that was done without verifying with a C test program.

=head1 BENCHMARKS

Counting leading zeros (clz) will be used to
benchmark the GCC builtin C<__builtin_clz()>
and a pure Perl implementation as suggested
by Perl Monk L
in this L

C operating on the binary representation of a number
counts the zeros starting from the most significant end until
it finds the first bit set (to 1). Which essentially gives the
zero-based index of the MSB set to 1.

The benchmarks favour the GCC builtin C<__builtin_clz()>
which is about twice as fast as the pure Perl implementation.

The benchmarks can be run with C
An easy way to let Perl fetch and unpack the distribution
for you is to use C to open a shell

   cpanm --look GCC::Builtins

and then

   perl Makefile.PL && make all && make test && make benchmarks

The following benchamrk results indicate that the use
of L (C in this case)
yields more than 100% performance gain
over equivalent pure perl code:

    Benchmark: timing 50000000 iterations of  clz/xs, clz/pp-ugly...
        clz/xs: 3.92331 wallclock secs ( 3.92 usr +  0.00 sys =  3.92 CPU) @ 12755102.04/s (n=50000000)
    clz/pp-ugly: 8.24574 wallclock secs ( 8.23 usr +  0.00 sys =  8.23 CPU) @ 6075334.14/s (n=50000000)
                      Rate clz/pp-ugly      clz/xs
    clz/pp-ugly  6075334/s          --        -52%
     clz/xs     12755102/s        110%          --
    KEY:
     clz/xs : calling GCC builtin clz() via XS from Perl
     clz/pp-ugly : as suggested by coldr3ality (see https://perlmonks.org/?node_id=11158279)

    Benchmark: timing 50000000 iterations of  clzl/xs, clzl/pp-ugly...
       clzl/xs: 3.84597 wallclock secs ( 3.84 usr +  0.00 sys =  3.84 CPU) @ 13020833.33/s (n=50000000)
    clzl/pp-ugly: 8.44006 wallclock secs ( 8.43 usr +  0.00 sys =  8.43 CPU) @ 5931198.10/s (n=50000000)
                       Rate clzl/pp-ugly      clzl/xs
    clzl/pp-ugly  5931198/s           --         -54%
     clzl/xs     13020833/s         120%           --
    KEY:
     clzl/xs : calling GCC builtin clzl() via XS from Perl
     clzl/pp-ugly : as suggested by coldr3ality (see https://perlmonks.org/?node_id=11158279)

So, it pays to use this module if performance is an issue.

=head1 CAVEATS

If you observe weird return results or core-dumps it is very likely that
the fault is mine while compiling the C. The file in the distribution
C was compiled by me to translate C's data types into Perls.
And for some of this I am not sure what the right type is. For example,
is C's C equivalent to Perl's C? How about
C's C mapping to Perl's C and C
to C?

Please L any corrections.

Note that C, C
and C are auto-generated by above scripts. Do not
edit them. Edit C
instead.

=head1 AUTHOR

Andreas Hadjiprocopis, C<<  >>

=head1 BUGS

Please report any bugs or feature requests to C, or through
the web interface at L.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc GCC::Builtins


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L


=item * Review this module at PerlMonks

L

=item * Search CPAN

L

=back


=head1 ACKNOWLEDGEMENTS

=over 2

=item * This module started by this discussion at PerlMonks:

L

=item * Hackers of Free Software.

=item * GNU and the Free Software Foundation, providers of GNU Compiler Collection.

=back

=head1 HUGS

!Almaz!


=head1 LICENSE AND COPYRIGHT

This software is Copyright (c) 2024 by Andreas Hadjiprocopis.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)


=cut

1; # End of GCC::Builtins