NAME

DiaColloDB::MultiMapFile - diachronic collocation db, integer->integer* multimap file, e.g. for expansion indices

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::MultiMapFile;
 
 ##========================================================================
 ## Constructors etc.
 
 $mmf = $CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## I/O: open/close (file)
 
 $mmf_or_undef = $mmf->open($base,$flags);
 $mmf_or_undef = $mmf->close();
 $bool = $mmf->opened();
 $bool = $mmf->dirty();
 $bool = $mmf->flush();
 \@a2b = $mmf->toArray();
 $mmf = $mmf->fromArray(\@a2b);
 $bool = $mmf->load();
 $mmf = $mmf->save();
 
 ##========================================================================
 ## I/O: header
 
 @keys = $coldb->headerKeys();
 $bool = $mmf->loadHeaderData($hdr);
 
 ##========================================================================
 ## I/O: text
 
 $mmf  = $CLASS_OR_OBJECT->loadTextFh($fh);
 $bool = $mmf->saveTextFh($fh,%opts);
 
 ##========================================================================
 ## Methods: population (in-memory only)
 
 $newsize = $mmf->addPairs($a,@bs);
 
 ##========================================================================
 ## Methods: lookup
 
 $bs_packed    = $mmf->fetchraw($a);
 \@bs_or_undef = $mmf->fetch($a);

DESCRIPTION

DiaColloDB::MultiMapFile provides an object-oriented interface for static integer->set(integer) multi-maps accessed via direct file I/O, used e.g. by native equivalence class expansion indices.

Globals & Constants

Variable: @ISA

DiaColloDB::MultiMapFile inherits from DiaColloDB::Persistent.

Constructors etc.

new

 $mmf = CLASS_OR_OBJECT->new(%args);

%args, object structure:

 base => $base,       ##-- database basename; use files "${base}.ma", "${base}.mb", "${base}.hdr"
 perms => $perms,     ##-- default: 0666 & ~umask
 flags => $flags,     ##-- default: 'r'
 pack_i => $pack_i,   ##-- integer pack template (default='N')
 size => $size,       ##-- number of mapped , like scalar(@data)
 ##
 ##-- in-memory construction
 a2b => \@a2b,        ##-- maps source integers to (packed) target integer-sets: [$a] => pack("${pack_i}*", @bs)
 ##
 ##-- computed pack templates and lengths (after open())
 pack_a => $pack_a,   ##-- "($pack_i)[2]"
 pack_b => $pack_a,   ##-- "($pack_i)*"
 len_i => $len_i,     ##-- bytes::length(pack($pack_i,0))
 len_a => $len_a,     ##-- bytes::length(pack($pack_a,0))
 ##
 ##-- filehandles (after open())
 afh => $afh,         ##-- $base.ma : [$a]      => pack(${pack_a}, $bidx_a, $blen_a) : $byte_offset_in_bfh = $len_i*$bidx_a
 bfh => $bfh,         ##-- $base.mb : [$bidx_a] => pack(${pack_b}, @targets_for_a)   : $byte_length_in_bfh = $len_i*$blen_a

NOTE: underlying file format changed from DiaColloDB v0.08.006 to v0.09.001; old-format files should be autodetected and a backwards-compatible API is offered by the DiaColloDB::MultiMapFile::v0_08 class.

DESTROY

Destructor implicitly calls close().

I/O: open/close (file)

open

 $mmf_or_undef = $mmf->open($base,$flags);
 $mmf_or_undef = $mmf->open($base);
 $mmf_or_undef = $mmf->open();

Open underlying files. Attempts to autodetect obsolete file formats and may re-bless $mmf into an appropriate compatibility package.

close

 $mmf_or_undef = $mmf->close();

Close underlying files. Implicitly calls flush() if opened for writing.

opened

 $bool = $mmf->opened();

Returns true iff underlying files are opened.

dirty

 $bool = $mmf->dirty();

Returns true iff some in-memory structures haven't been flushed to disk.

flush

 $bool = $mmf->flush();

• flush in-memory structures to disk

• clobbers any old disk-file contents with in-memory maps

• multimap must be opened in write-mode

• invalidates any old references to {a2b} (but doesn't empty them if you need to keep a reference)

toArray

 \@a2b = $mmf->toArray();

returns an in-memory dump of the multimap contents as a perl ARRAY-ref indexed by $a whose values are packed strings of the $b items associated with $a:

 @bs = unpack("$mmf->{pack_i}*", $a2b[$a]);

fromArray

 $mmf = $mmf->fromArray(\@a2b);

Populate from perl array. Clobbers $mmf contents, steals \@a2b.

load

 $bool = $mmf->load();

loads files to memory; must be opened.

save

 $mmf = $mmf->save();
 $mmf = $mmf->save($base);

saves multimap to $base; really just a wrapper for open() and flush().

I/O: header

See also DiaColloDB::Persistent.

headerKeys

 @keys = $coldb->headerKeys();

keys to save as header

loadHeaderData

 $bool = $mmf->loadHeaderData($hdr);

override.

I/O: text

See also DiaColloDB::Persistent.

loadTextFh

 $mmf = $CLASS_OR_OBJECT->loadTextFh($fh,%opts);

Loads from text file with lines of the form "A B1 B2...", clobbering any pre-existing multimap contents.

saveTextFh

 $bool = $mmf->saveTextFh($fh,%opts);

Save to text file with lines of the form "A B1 B2...". %opts:

 a2s=>\&a2s  ##-- stringification code for A items, called as $s=$a2s->($bi)
 b2s=>\&b2s  ##-- stringification code for B items, called as $s=$b2s->($bi)

Methods: population (in-memory only)

addPairs

 $newsize = $mmf->addPairs($a,@bs);
 $newsize = $mmf->addPairs($a,\@bs)

adds mappings $a=>$b foreach $b in @bs. multimap must be loaded to memory.

Methods: lookup

fetchraw

 $bs_packed = $mmf->fetchraw($a);

Returns a packed array $bs_packed = pack($mmf->{pack_b}, @bs) of targets for $a, or undef if not found. multimap must be opened.

fetch

 \@bs_or_undef = $mmf->fetch($a);

Returns array \@bs of targets for $a, or undef if not found. multimap must be opened.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015-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::MultiMapFile::MMap(3pm), DiaColloDB::MultiMapFile::v0_08(3pm), DiaColloDB::Persistent(3pm), DiaColloDB(3pm), perl(1), ...