##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::PackedFile::MMap - collocation db: flat fixed-length record-oriented files; mmap variant

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::PackedFile::MMap;
 
 ##========================================================================
 ## Constructors etc.
 
 $pf = CLASS_OR_OBJECT->new(%opts);
 
 ##========================================================================
 ## API: open/close
 
 $pf   = $pf->open();
 $bool = $pf->remap();
 $bool = $pf->opened();
 $bool = $pf->close();
 $bool = $pf->setsize($nrecords);
 $bool = $pf->truncate();
 
 ##========================================================================
 ## API: positioning
 
 $nrecords = $pf->size();
 
 $bool  = $pf->seek($recno);
 $recno = $pf->tell();
 
 $bool = $pf->reset();
 $bool = $pf->seekend();
 $bool = $pf->eof();
 
 ##========================================================================
 ## API: record access: read
 
 $bool = $pf->read(\$buf);
 $bool = $pf->readraw(\$buf, $nrecords);
 
 $value_or_undef = $pf->get();
 \$buf_or_undef  = $pf->getraw(\$buf);
 
 $value_or_undef = $pf->fetch($index);
 $buf_or_undef   = $pf->fetchraw($index,\$buf);
 
 ##========================================================================
 ## API: record access: write
 
 $bool = $pf->write($buf);
 $value_or_undef = $pf->set($value);
 $value_or_undef = $pf->store($index,$value);
 $value_or_undef = $pf->push($value);
 
 ##========================================================================
 ## API: batch I/O
 
 \@data = $pf->toArray(%opts);
 $pf = $pf->fromArray(\@data,%opts);
 
 ##========================================================================
 ## API: binary search
 
 $nbits_or_undef = $pf->vnbits();
 $index_or_undef = $pf->bsearch($key, %opts);
 
 ##========================================================================
 ## I/O: text
 
 $bool = $pf->saveTextFh($fh, %opts);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

DiaColloDB::PackedFile::MMap uses the
L<File::Map|File::Map> module to provide a fast mmap()-based interface to
record-based binary files supported by the L<DiaColloDB::PackedFile|DiaColloDB::PackedFile> class,
from which it inherits.


=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::PackedFile::MMap
inherits from
L<DiaColloDB::PackedFile|DiaColloDB::PackedFile> and supports the
L<DiaColloDB::PackedFile|DiaColloDB::PackedFile> API.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $pf = CLASS_OR_OBJECT->new(%opts);

%opts, %$pf:

 ##-- PackedFile: user options
 file     => $filename,   ##-- default: undef (none)
 flags    => $flags,      ##-- fcntl flags or open-mode (default='r')
 perms    => $perms,      ##-- creation permissions (default=(0666 &~umask))
 reclen   => $reclen,     ##-- record-length in bytes: (default: guess from pack format if available)
 packas   => $packas,     ##-- pack-format or array; see DiaColloDB::Utils::packFilterStore();
 ##
 ##-- PackedFile: filters
 filter_fetch => $filter, ##-- DB_File-style filter for fetch
 filter_store => $filter, ##-- DB_File-style filter for store
 ##
 ##-- PackedFile: filehandles
 fh       => $fh,         ##-- underlying filehandle
 ##
 ##-- PackedFile::MMap: mmap buffers
 bufr     => \$buf,       ##-- mmap $fh
 bufp     => $bufp,       ##-- current buffer position (logical record number), for filehandle emulation

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: API: open/close
=pod

=head2 API: open/close

=over 4

=item open

 $pf = $pf->open();
 $pf = $pf->open($file);
 $pf = $pf->open($file,$flags,%opts);

overrides L<DiaColloDB::PackedFile::open|DiaColloDB::PackedFile/open>().

=item remap

 $bool = $pf->remap();

re-maps C<$pf-E<gt>{bufr}> from C<$pf-E<gt>{fh}>.

=item opened

 $bool = $pf->opened();

overrides L<DiaColloDB::PackedFile::opened|DiaColloDB::PackedFile/opened>():
checks for defined $pf-E<gt>{bufr}.

=item close

 $bool = $pf->close();

overrides L<DiaColloDB::PackedFile::close|DiaColloDB::PackedFile/close>():
deletes $pf-E<gt>{bufr}.

=item setsize

 $bool = $pf->setsize($nrecords);

overrides L<DiaColloDB::PackedFile::setsize|DiaColloDB::PackedFile/setsize>():
calls L<remap|/remap>().

=item truncate

 $bool = $pf->truncate();

overrides L<DiaColloDB::PackedFile::truncate|DiaColloDB::PackedFile/truncate>():
calls L<remap|/remap>().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: API: positioning
=pod

=head2 API: positioning

=over 4

=item size

 $nrecords = $pf->size();

returns number of records

=item seek

 $bool = $pf->seek($recno);

seek to record-number $recno

=item tell

 $recno = $pf->tell();

report current record-number

=item reset

 $bool = $pf->reset();

reset position to beginning of file

=item seekend

 $bool = $pf->seekend();

seek to end-of file

=item eof

 $bool = $pf->eof();

returns true iff current position is end-of-file

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: API: record access: read
=pod

=head2 API: record access: read

=over 4

=item read

 $bool = $pf->read(\$buf);

read a raw record into \$buf

=item readraw

 $bool = $pf->readraw(\$buf, $nrecords);

batch-reads $nrecords into \$buf

=item get

 $value_or_undef = $pf->get();

get (unpacked) value of current record, increments filehandle position to next record

=item getraw

 \$buf_or_undef = $pf->getraw(\$buf);

get (packed) value of current record, increments filehandle position to next record

=item fetch

 $value_or_undef = $pf->fetch($index);

get (unpacked) value of record $index

=item fetchraw

 $buf_or_undef = $pf->fetchraw($index,\$buf);

get (packed) value of record $index

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: API: record access: write
=pod

=head2 API: record access: write

=over 4

=item write

 $bool = $pf->write($buf);

write a raw record $buf to current position; increments position

=item set

 $value_or_undef = $pf->set($value);

set (packed) value of current record, increments filehandle position to next record

=item store

 $value_or_undef = $pf->store($index,$value);

store (packed) $value as record-number $index

=item push

 $value_or_undef = $pf->push($value);

store (packed) $value at end of record

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: API: batch I/O
=pod

=head2 API: batch I/O

=over 4

=item toArray

 \@data = $pf->toArray(%opts);

read entire file contents to an array.

=item fromArray

 $pf = $pf->fromArray(\@data,%opts);

write file contents from an array

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: API: binary search
=pod

=head2 API: binary search

=over 4

=item vnbits

 $nbits_or_undef = $pf->vnbits();

returns number of bits for using vec()-style search via Algorithm::BinarySearch::Vec, or undef if not supported

still B<UNUSED>

=item bsearch

 $index_or_undef = $pf->bsearch($key, %opts);

Optimized version of L<DiaColloDB::PackedFile::bsearch|DiaColloDB::PackedFile/bsearch>() method.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PackedFile::MMap: I/O: text
=pod

=head2 I/O: text

=over 4

=item saveTextFh

save from text file with lines of the form "KEY? VALUE(s)..."

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<DiaColloDB::PackedFile(3pm)|DiaColloDB::PackedFile>,
L<perl(1)|perl>,
...


=cut
