/ 
DiaColloDB-0.12.020
River stage one • 1 direct dependent • 1 total dependent
/ DiaColloDB::MultiMapFile

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-2020 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), ...