NAME

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

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);
 

DESCRIPTION

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

Globals & Constants

Variable: @ISA

DiaColloDB::PackedFile::MMap inherits from DiaColloDB::PackedFile and supports the DiaColloDB::PackedFile API.

Constructors etc.

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

API: open/close

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

overrides DiaColloDB::PackedFile::open().

remap
 $bool = $pf->remap();

re-maps $pf->{bufr} from $pf->{fh}.

opened
 $bool = $pf->opened();

overrides DiaColloDB::PackedFile::opened(): checks for defined $pf->{bufr}.

close
 $bool = $pf->close();

overrides DiaColloDB::PackedFile::close(): deletes $pf->{bufr}.

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

overrides DiaColloDB::PackedFile::setsize(): calls remap().

truncate
 $bool = $pf->truncate();

overrides DiaColloDB::PackedFile::truncate(): calls remap().

API: positioning

size
 $nrecords = $pf->size();

returns number of records

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

seek to record-number $recno

tell
 $recno = $pf->tell();

report current record-number

reset
 $bool = $pf->reset();

reset position to beginning of file

seekend
 $bool = $pf->seekend();

seek to end-of file

eof
 $bool = $pf->eof();

returns true iff current position is end-of-file

API: record access: read

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

read a raw record into \$buf

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

batch-reads $nrecords into \$buf

get
 $value_or_undef = $pf->get();

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

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

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

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

get (unpacked) value of record $index

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

get (packed) value of record $index

API: record access: write

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

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

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

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

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

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

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

store (packed) $value at end of record

API: batch I/O

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

read entire file contents to an array.

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

write file contents from an array

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 UNUSED

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

Optimized version of DiaColloDB::PackedFile::bsearch() method.

I/O: text

saveTextFh

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

AUTHOR

Bryan Jurish <moocow@cpan.org>

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.

SEE ALSO

DiaColloDB::PackedFile(3pm), perl(1), ...