=head1 NAME

XSConfig - Fast XS drop-in replacement for Config.pm with perfect hashing.

=head1 VERSION

Version 6.11

=head1 SYNOPSIS

The Config.pm included by default with Perl is pure Perl.  Nearly all Perl apps
will load Config.pm.  For a number of reasons, of speed and memory space,
reimplement the P5P shipped Config.pm as an XS library, shareable between
processes as read-only memory, and with a hash that is better optimized than
Perl hashes, courtesy of gperf tool which generates collision-free perfect
hashes.

This module is a drop-in replacement for Config.pm. All code that does

    use Config;

will use the XS implementation after installing this module.  To revert to the
original pure perl Config.pm, go and delete the following 3 files that will be
next to each other in /site, Config.pm, Config_mini.pl, Config_xs_heavy.pl, and
the Config shared library in /auto, after deleting the /site files, the original
pure perl Config.pm in /lib will be loaded.

Since XS Config is a compiled C shared library, it can not be edited with a text
editor after it is built.  To change the values in the XS Config module,
edit the pure perl Config_heavy.pl file with a text editor and rebuild XS
Config.

IT IS HIGHLY RECOMMENDED THAT YOU HAVE GPERF TOOL INSTALLED AND RUNNABLE FROM
YOUR PATH BEFORE INSTALLING XS CONFIG.

=head1 BENCHMARKS

    perl -MXSLoader -MConfig -e"sleep 1000"

    Memory Usage KB	Total	Image Committed	Image Private	Heap Private
    With PP Config	36,976	11,376		272		668
    With XS Config	37,188	11,492		280		640

Using XSConfig 6.11, with a VC 2013 32 bit threaded perl, you save 20 KB of per
process memory, in exchange for 108 KB of shared between process, memory mapped
(Config.dll) memory. That is an increase in memory usage of 88 KB if you have
just a single perl process ever running on the machine at a time, but around 4
perl processes with XS Config, XS Config uses less memory than the equivelent
group of perl processes with PP Config.

The total size of Config.dll in memory is 116 KB, with 8 KB of
unshareable memory, the rest is shared. The smallest (no XSUBs except boot)
Win32 XS DLL without taking special measures is 24 KB, with 8 KB of unshareable
memory. So around ~24 KB is the overhead of a Visual C 2013 DLL with all the
C compiler specific hidden static linked functions inside the DLL (these can
be removed, but it is "special measures" that aren't typical on Win32 Perls).

Onto performance, to slurp the entire tied %Config hash into a non-tied hash,
with XS Config is %36 faster than with PP Config. To read 1 key in the tied
%Config hash is 15% faster than with PP Config.

Raw data with XS Config

    C:\sources>timeit -f t.dat perl -MXSLoader -MConfig -e"print
    $Config::VERSION.\"\n\";my %h; %h = %Config for 0..1000"
    6.11
    
    Version Number:   Windows NT 6.1 (Build 7601)
    Exit Time:        4:32 pm, Tuesday, January 19 2016
    Elapsed Time:     0:00:10.296
    Process Time:     0:00:10.249
    System Calls:     27201
    Context Switches: 3953
    Page Faults:      3497
    Bytes Read:       94500
    Bytes Written:    97108
    Bytes Other:      13422
    
    C:\sources>timeit -f t.dat perl -MXSLoader -MConfig -e"print
    $Config::VERSION.\"\n\";my $v; $v = $Config{'ccflags'} for 0..1000000;print
    $v"
    6.11
    -nologo -GF -W3 -O1 -MD -Zi -DNDEBUG -GL -DWIN32 -D_CONSOLE -DNO_STRICT -D_CRT_S
    ECURE_NO_DEPRECATE -D_CRT_NONSTDC_NO_DEPRECATE  -DPERL_TEXTMODE_SCRIPTS -DPERL_I
    MPLICIT_CONTEXT -DPERL_IMPLICIT_SYS
    Version Number:   Windows NT 6.1 (Build 7601)
    Exit Time:        4:32 pm, Tuesday, January 19 2016
    Elapsed Time:     0:00:05.226
    Process Time:     0:00:05.226
    System Calls:     12385
    Context Switches: 1843
    Page Faults:      2226
    Bytes Read:       91738
    Bytes Written:    0
    Bytes Other:      7528

With PP Config

    
    C:\sources>timeit -f t.dat perl -MXSLoader -MConfig -e"print
    $Config::VERSION.\"\n\";my %h; %h = %Config for 0..1000"
    5.023005
    
    Version Number:   Windows NT 6.1 (Build 7601)
    Exit Time:        4:33 pm, Tuesday, January 19 2016
    Elapsed Time:     0:00:16.068
    Process Time:     0:00:16.005
    System Calls:     42186
    Context Switches: 5417
    Page Faults:      4607
    Bytes Read:       136490
    Bytes Written:    0
    Bytes Other:      22281
    
    C:\sources>timeit -f t.dat perl -MXSLoader -MConfig -e"print
    $Config::VERSION.\"\n\";my $v; $v = $Config{'ccflags'} for 0..1000000;print
    $v"
    5.023005
    -nologo -GF -W3 -O1 -MD -Zi -DNDEBUG -GL -DWIN32 -D_CONSOLE -DNO_STRICT -D_CRT_S
    ECURE_NO_DEPRECATE -D_CRT_NONSTDC_NO_DEPRECATE  -DPERL_TEXTMODE_SCRIPTS -DPERL_I
    MPLICIT_CONTEXT -DPERL_IMPLICIT_SYS
    Version Number:   Windows NT 6.1 (Build 7601)
    Exit Time:        4:33 pm, Tuesday, January 19 2016
    Elapsed Time:     0:00:06.146
    Process Time:     0:00:06.130
    System Calls:     15062
    Context Switches: 2248
    Page Faults:      2381
    Bytes Read:       131566
    Bytes Written:    0
    Bytes Other:      8414
    
    C:\sources>

=head1 AUTHOR

Daniel Dragan C<< <BULKDD at cpan.org> >>
Reini Urban C<< <rurban at cpanel.net> >>

=head1 LICENSE AND COPYRIGHT

Copyright (C) 2015, Daniel Dragan
Copyright (C) 2015, cPanel Inc
 
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut
