Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5001.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/Sort::External.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sort::External 3"
.TH Sort::External 3 "2005-11-30" "perl v5.8.8" "User Contributed Perl Documentation"
.PP
.Vb 10
\&    $self->_write_item_cache_to_tempfile;
\&    for my $input_level ( 0 .. $#{ $self->{sortfiles} } ) {
\&        if ($final) {
\&            $self->_consolidate_one_level($input_level);
\&        }
\&        elsif ( @{ $self->{sortfiles}[$input_level] } > MAX_SORTFILES ) {
\&            $self->_consolidate_one_level($input_level);
\&        }
\&    }
\&}
.Ve
.PP
# merge multiple sortfiles
sub _consolidate_one_level {
    my ( \f(CW$self\fR, \f(CW$input_level\fR ) = \f(CW@_\fR;
    my \f(CW$sortsub\fR = \f(CW$self\fR\->{\-sortsub};
.PP
.Vb 2
\&    # create a holder for the output filehandles if necessary.
\&    $self->{sortfiles}[ $input_level + 1 ] ||= [];
.Ve
.PP
.Vb 7
\&    # if there's only one sortfile on this level, kick it up and return
\&    if ( @{ $self->{sortfiles}[$input_level] } == 1 ) {
\&        push @{ $self->{sortfiles}[ $input_level + 1 ] },
\&            @{ $self->{sortfiles}[$input_level] };
\&        $self->{sortfiles}[$input_level] = [];
\&        return;
\&    }
.Ve
.PP
.Vb 5
\&    # get a new outfile
\&    my $outfile = File::Temp->new(
\&        DIR    => $self->{workdir},
\&        UNLINK => 1
\&    );
.Ve
.PP
.Vb 7
\&    # build an array of Sort::External::Buffer objects, one per filehandle
\&    my @in_buffers;
\&    for my $tf_handle ( @{ $self->{sortfiles}[$input_level] } ) {
\&        seek( $tf_handle, 0, 0 );
\&        my $buff = Sort::External::Buffer->_new( tf_handle => $tf_handle, );
\&        push @in_buffers, $buff;
\&    }
.Ve
.PP
.Vb 2
\&    while (@in_buffers) {
\&        my @on_the_bubble;
.Ve
.PP
.Vb 11
\&        # discard exhausted buffers, collect endposts
\&        my @buffer_buffer;
\&        for my $buff (@in_buffers) {
\&            if ( !@{ $buff->{buffarray} } ) {
\&                next unless $buff->_refill_buffer;
\&            }
\&            push @on_the_bubble, $buff->{buffarray}[-1];
\&            push @buffer_buffer, $buff;
\&        }
\&        last unless @buffer_buffer;
\&        @in_buffers = @buffer_buffer;
.Ve
.PP
.Vb 5
\&        # choose the cutoff from among the endpost candidates
\&        @on_the_bubble = $sortsub
\&            ? ( sort $sortsub @on_the_bubble )
\&            : ( sort @on_the_bubble );
\&        my $cutoff = $on_the_bubble[0];
.Ve
.PP
.Vb 15
\&        # create a closure sub that compares an arg to the cutoff
\&        my $comparecode;
\&        if ( defined $sortsub ) {
\&            $comparecode = sub {
\&                my $test = shift;
\&                return 0 if $test eq $cutoff;
\&                my $winner = ( sort $sortsub( $cutoff, $test ) )[0];
\&                return $winner eq $cutoff ? 1 : -1;
\&            };
\&        }
\&        else {
\&            $comparecode = sub {
\&                return $_[0] cmp $cutoff;
\&            };
\&        }
.Ve
.PP
.Vb 7
\&        # build the batch
\&        my @batch;
\&        for my $buff (@in_buffers) {
\&            $buff->_define_range($comparecode);
\&            next if $buff->{max_in_range} == -1;
\&            my $num_to_splice = $buff->{max_in_range} + 1;
\&            push @batch, splice( @{ $buff->{buffarray} }, 0, $num_to_splice );
.Ve
.PP
.Vb 1
\&        }
.Ve
.PP
.Vb 4
\&        # sort the batch and print it to an outfile
\&        @batch = $sortsub ? ( sort $sortsub @batch ) : ( sort @batch );
\&        _print_to_sortfile( $outfile, @batch );
\&    }
.Ve
.PP
.Vb 4
\&    # explicity close the filehandles that were consolidated; since they're
\&    # tempfiles, they'll unlink themselves
\&    close $_ for @{ $self->{sortfiles}[$input_level] };
\&    $self->{sortfiles}[$input_level] = [];
.Ve
.PP
.Vb 4
\&    # add the outfile to the next higher level of the sortfiles array
\&    seek( $outfile, 0, 0 );
\&    push @{ $self->{sortfiles}[ $input_level + 1 ] }, $outfile;
\&}
.Ve
.PP
package Sort::External::Buffer;
use strict;
use warnings;
.PP
use Clone 'clone';
.PP
our \f(CW%class_defaults\fR = (
    buffarray    => [],
    max_in_range => \-1,
    tf_handle    => undef,
);
.PP
sub _new {
    my \f(CW$class\fR = shift;
    my \f(CW$self\fR  = clone( \e%class_defaults );
    %$self = ( %$self, \f(CW@_\fR );
    bless \f(CW$self\fR, \f(CW$class\fR;
}
.PP
# record the highest index in the buffarray representing an element lower than
# a given cutoff.
sub _define_range {
    my ( \f(CW$self\fR, \f(CW$comparecode\fR ) = \f(CW@_\fR;
    my \f(CW$buffarray\fR = \f(CW$self\fR\->{buffarray};
    my ( \f(CW$lo\fR, \f(CW$mid\fR, \f(CW$hi\fR ) = ( 0, 0, $#$buffarray );
.PP
.Vb 8
\&    # divide and conquer
\&    while ( $hi - $lo > 1 ) {
\&        $mid = ( $lo + $hi ) >> 1;
\&        my $delta = &$comparecode( $buffarray->[$mid] );
\&        if    ( $delta == -1 ) { $lo = $mid }
\&        elsif ( $delta == 1 )  { $hi = $mid }
\&        elsif ( $delta == 0 )  { $lo = $hi = $mid }
\&    }
.Ve
.PP
.Vb 9
\&    # get that last item in...
\&    while ( $mid < $#$buffarray
\&        and &$comparecode( $buffarray->[ $mid + 1 ] ) < 1 )
\&    {
\&        $mid++;
\&    }
\&    while ( $mid >= 0 and $comparecode->( $buffarray->[$mid] ) == 1 ) {
\&        $mid--;
\&    }
.Ve
.PP
.Vb 3
\&    # store the index for the last item we'll allow through
\&    $self->{max_in_range} = $mid;
\&}
.Ve
.PP
1;
.PP
_\|_END_\|_
.SH "NAME"
Sort::External \- sort huge lists
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&    my $sortex = Sort::External->new( -mem_threshold => 2**24 );
\&    while (<HUGEFILE>) {
\&        $sortex->feed($_);
\&    }
\&    $sortex->finish;
\&    while ( defined( $_ = $sortex->fetch ) ) {
\&        &do_stuff_with($_);
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Problem: You have a list which is too big to sort in\-memory.  
.PP
Solution: \*(L"feed, finish, and fetch\*(R" with Sort::External, the closest thing to
a drop-in replacement for Perl's \fIsort()\fR function when dealing with
unmanageably large lists.
.Sh "How it works"
.IX Subsection "How it works"
Cache sortable items in memory.  Periodically sort the cache and empty it into
a temporary sortfile.  As sortfiles accumulate, interleave them into larger
sortfiles.  Complete the sort by sorting the input cache and any existing
sortfiles into an output stream.
.PP
Note that if Sort::External hasn't yet flushed the cache to disk when \fIfinish()\fR
is called, the whole operation completes in\-memory.
.PP
In the CompSci world, \*(L"internal sorting\*(R" refers to sorting data in \s-1RAM\s0, while
\&\*(L"external sorting\*(R" refers to sorting data which is stored on disk, tape,
punchcards, or any storage medium except \s-1RAM\s0 \*(-- hence, this module's name.
.Sh "Stringification"
.IX Subsection "Stringification"
Items fed to Sort::External will be returned in stringified form (assuming
that the cache gets flushed at least once): \f(CW\*(C`$foo = "$foo"\*(C'\fR.  Since this is
unlikely to be desirable when objects or deep data structures are involved,
Sort::External throws an error if you feed it anything other than simple
scalars.   
.Sh "Taint and \s-1UTF\-8\s0 flags"
.IX Subsection "Taint and UTF-8 flags"
Expert: Sort::External does a little extra bookkeeping to sustain each item's
taint and \s-1UTF\-8\s0 flags through the journey to disk and back.
.SH "METHODS"
.IX Header "METHODS"
.Sh "\fInew()\fP"
.IX Subsection "new()"
.Vb 7
\&    my $sortscheme = sub { $Sort::External::b <=> $Sort::External::a };
\&    my $sortex = Sort::External->new(
\&        -mem_threshold   => 2**24,            # default: 2**20 (1Mb)
\&        -cache_size      => 100_000,          # default: undef (disabled) 
\&        -sortsub         => $sortscheme,      # default sort: standard lexical
\&        -working_dir     => $temp_directory,  # default: see below
\&    );
.Ve
.PP
Construct a Sort::External object.
.IP "\(bu" 4
\&\fB\-mem_threshold\fR \*(-- Allow the input cache to consume approximately
\&\-mem_threshold bytes before sorting it and flushing to disk.  Experience
suggests that the optimum setting is somewhere between 2**20 and 2**24:
1\-16Mb.
.IP "\(bu" 4
\&\fB\-cache_size\fR \*(-- Specify a hard limit for the input cache in terms of
sortable items.  If set, overrides \-mem_threshold. 
.IP "\(bu" 4
\&\fB\-sortsub\fR \*(-- A sorting subroutine.  Be advised that you \s-1MUST\s0 use
\&\f(CW$Sort::External::a\fR and \f(CW$Sort::External::b\fR instead of \f(CW$a\fR and \f(CW$b\fR in your sub.
Before deploying a sortsub, consider using a \s-1GRT\s0 instead, as described in
the Sort::External::Cookbook. It's probably
a lot faster.
.IP "\(bu" 4
\&\fB\-working_dir\fR \*(-- The directory where the temporary sortfiles will reside.
By default, this directory is created using File::Temp's
\&\fItempdir()\fR command.
.Sh "\fIfeed()\fP"
.IX Subsection "feed()"
.Vb 1
\&    $sortex->feed( @items );
.Ve
.PP
Feed one or more sortable items to your Sort::External object.  It is normal
for occasional pauses to occur during feeding as caches are flushed and
sortfiles are merged.
.Sh "\fIfinish()\fP"
.IX Subsection "finish()"
.Vb 2
\&    # if you intend to call fetch...
\&    $sortex->finish;
.Ve
.PP
.Vb 6
\&    # otherwise....
\&    use Fcntl;
\&    $sortex->finish( 
\&        -outfile => 'sorted.txt',
\&        -flags => (O_CREAT | O_WRONLY),
\&    );
.Ve
.PP
Prepare to output items in sorted order.
.PP
If you specify the parameter \-outfile, Sort::External will attempt to write
your sorted list to that location.  By default, Sort::External will refuse to
overwrite an existing file; if you want to override that behavior, you can
pass Fcntl flags to \fIfinish()\fR using the optional \-flags parameter.
.PP
Note that you can either \fIfinish()\fR to an \-outfile, or \fIfinish()\fR then \fIfetch()\fR...
but not both.  
.Sh "\fIfetch()\fP"
.IX Subsection "fetch()"
.Vb 3
\&    while ( defined( $_ = $sortex->fetch ) ) {
\&        &do_stuff_with($_);
\&    }
.Ve
.PP
Fetch the next sorted item.  
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-sort\-external@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sort\-External>.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Bug reports and patches: Ken Clarke, Chris Nandor, Alessandro Ranellucci.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The Sort::External::Cookbook.
.PP
File::Sort, File::MergeSort, and 
Sort::Merge as possible alternatives.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marvin Humphrey <marvin at rectangular dot com>
<http://www.rectangular.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005 Marvin Humphrey.  All rights reserved.
This module is free software.  It may be used, redistributed and/or 
modified under the same terms as Perl itself.
Creat By MiNi SheLL
Email: devilkiller@gmail.com