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

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

=head1 NAME

DiaColloDB::MultiMapFile::MMap - collocation db, integer->integer* multimap file, using mmap

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::MultiMapFile::MMap;
 
 ##========================================================================
 ## Constructors etc.
 
 $mmf = CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## I/O: open/close (file)
 
 $mmf_or_undef = $mmf->open($base,$flags);
 $mmf_or_undef = $mmf->mmap_open();
 $mmf_or_undef = $mmf->mmap_close();
 $mmf_or_undef = $mmf->close();
 $bool = $mmf->opened();
 \@a2b = $mmf->toArray();
 
 ##========================================================================
 ## Methods: lookup
 
 $bs_packed = $mmf->fetchraw($a);
 

=cut

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

=head1 DESCRIPTION

=cut

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

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::MultiMapFile::MMap
inherits from 
L<DiaColloDB::MultiMapFile|DiaColloDB::MultiMapFile>
and supports the L<DiaColloDB::MultiMapFile|DiaColloDB::MultiMapFile> read-access API.

=back

=cut

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

=head2 Constructors etc.

=over 4

=item new

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

%args, object structure:

   (
    ##-- MultiMapFile: basic options
    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)
    ##
    ##-- MultiMapFile: in-memory construction
    a2b => \@a2b,        ##-- maps source integers to (packed) target integer-sets: [$a] => pack("${pack_i}*", @bs)
    ##
    ##-- MultiMapFile: 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))
    ##
    ##-- MultiMapFile: 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
    ##
    ##-- MultiMapFile::MMap: buffers
    abufr => \$abuf,     ##-- mmap $base.ma
    bbufr => \$bbuf,     ##-- mmap $base.mb
   )

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::MultiMapFile::MMap: I/O: open/close (file)
=pod

=head2 I/O: open/close (file)

=over 4

=item open

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

Open underlying files.
See L<DiaColloDB::MultiMapFile::open|DiaColloDB::MultiMapFile/open>().

=item mmap_open

 $mmf_or_undef = $mmf->mmap_open();

mmaps local buffers C<@$mmf{qw(abufr bbufr)}> from C<@$mmf{qw(afh bfh)}>.

=item mmap_close

 $mmf_or_undef = $mmf->mmap_close();

un-references local buffers C<@$mmf{qw(abufr bbufr)}>.

=item close

 $mmf_or_undef = $mmf->close();

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

=item opened

 $bool = $mmf->opened();

Returns true iff underlying files are opened and local buffers are defined.

=item toArray

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

See L<DiaColloDB::MultiMapFile::toArray|DiaColloDB::MultiMapFile/toArray>().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::MultiMapFile::MMap: Methods: lookup
=pod

=head2 Methods: lookup

=over 4

=item fetchraw

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

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

=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<dcdb-create.per(1)|dcdb-create.perl>,
L<dcdb-query.perl(1)|dcdb-query.perl>,
L<dcdb-info.perl(1)|dcdb-info.perl>,
L<dcdb-export.perl(1)|dcdb-export.perl>,
L<dcdb-dump.perl(1)|dcdb-dump.perl>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
