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

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

=head1 NAME

DiaColloDB::PDL::MM - DiaColloDB utilities: (temporary) mmaped PDLs

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::PDL::MM;
 
 ##========================================================================
 ## Constructors etc.
 
 $mmpdl = CLASS->new($file?, $type?, @dims, \%opts?);
 $mmpdl = CLASS->mmtemp($file?, $type?, @dims, \%opts?);
 $bool = CLASS->unlink(@basenames);
 undef = $obj->DESTROY();
 
 ##========================================================================
 ## Accessors
 
 $file = $mmdpl->file();
 $istmp = $mmdpl->temp();
 $pdl = $mmpdl->_pdl();
 

=cut

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

=head1 DESCRIPTION

DiaColloDB::PDL::MM provides a simple object-oriented wrapper
for (temporary) PDLs using mmap() via L<PDL::IO::FastRaw|PDL::IO::FastRaw>.
This is mostly useful to ensure that the memory used by large intermediate
piddles is freed when the objects are destroyed, since mmap() bypasses
perl's internal memory management.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PDL::MM: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::PDL::MM inherits from L<PDL|PDL>.

=item Variable: %MMTMP

Psuedo-set of all tempfiles created, used by END block.

=item Variable: $LOG_DEFAULT

Default log-level for debugging (default=undef: off).

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PDL::MM: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $mmpdl = CLASS->new($file?, $type?, @dims, \%opts?);
 $mmpdl = $pdl->mmzeroes($file?, $type?, \%opts?);

Creates and returns a new mmap()ed PDL and returns the result
as a blessed HASH-ref conforming to PDL inheritance conventions.
%opts, %$mmpdl:

 (
  file => $template,   ##-- file basename or File::Temp template; default='pdlXXXX'
  suffix => $suffix,   ##-- File::Temp::tempfile() suffix (default='.pdl')
  log  => $level,      ##-- logging verbosity (default=$LOG_DEFAULT)
  temp => $bool,       ##-- delete on END (default: $file =~ /X{4}/)
  PDL  => $pdl,        ##-- guts: real underlying mmap()ed piddle (must be key 'PDL' for PDL inheritance to work)
 )

=item mmtemp

 $mmpdl = CLASS->mmtemp($file?, $type?, @dims, \%opts?);

like new(), but always sets C<$opts-E<gt>{temp}=1>.

=item unlink

 $bool = CLASS->unlink(@basenames);
 $bool = $mmpdl->unlink();

Unlinks file(s) generated by C<mmzeroes($basename)>.
C<$basename> defaults to C<$mmpdl-E<gt>{file}> if called as an object method.

=item DESTROY

 undef = $obj->DESTROY()

Destructor implicitly calls unlink();
must also handle "pure" piddles created e.g. by $mmpdl-E<gt>xvals().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::PDL::MM: Accessors
=pod

=head2 Accessors

=over 4

=item file

 $file = $mmdpl->file();

Returns mmap()ed filename.

=item temp

 $istmp = $mmdpl->temp();

Returns true iff $mmpdl is marked as a temporary.

=item _pdl

 $pdl = $mmpdl->_pdl();

Returns "real" underlying PDL.

=back

=cut

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

=head1 AUTHOR

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

=head1 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.

=head1 SEE ALSO

L<PDL(3pm)|PDL>,
L<PDL::IO::FastRaw(3pm)|PDL::IO::FastRaw>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...

=cut
