view release on metacpan or  search on metacpan

lib/File/Locate/Iterator.pm  view on Meta::CPAN

or

    while (my ($filename) = $it->next) ...

The return is a byte string since it's normally a filename and Perl handles
filenames as byte strings.

=item C<< $it->rewind() >>

Rewind C<$it> back to the start of the database.  The next C<$it-E<gt>next>
call will return the first entry.

This is only possible when the underlying database file or handle is
seekable, ie. C<seek()> works.  This means a plain file, or a seekable char
special, or PerlIO layers with seek support.

=back

=head1 ENVIRONMENT VARIABLES

=over 4

=item C<LOCATE_PATH>

Default locate database.

=back

=head1 FILES

=over 4

=item F</var/cache/locate/locatedb>

Default locate database, if C<LOCATE_PATH> environment variable not set.

=back

=head1 OTHER WAYS TO DO IT

C<File::Locate> reads a locate database with callbacks instead.  Whether you
want callbacks or an iterator is generally a matter of personal preference.
Iterators let you write your own loop, and can have multiple searches in
progress simultaneously.

The speed of an iterator is about the same as callbacks when
C<File::Locate::Iterator> is built with its XS code.

Iterators are good for cooperative coroutining like C<POE> or C<Gtk> where
state must be held in some sort of variable to be progressed by calls from
the main loop.  Note that C<next()> will block on reading from the database,
so the database should generally be a plain file rather than a socket or
something, so as not to hold up a main loop.

If you have the recommended C<File::Map> module then iterators share an
C<mmap()> of the database file.  Otherwise the database file is a separate
open handle in each iterator, meaning a file descriptor and PerlIO buffering
each.  Sharing a handle and having each seek to its desired position would
be possible, but a seek drops buffered data so would be slower.  Maybe some
hairy C<PerlIO> or C<IO::Handle> trickery could transparently share an fd
and keep buffered blocks from multiple file positions.

=head1 SEE ALSO

L<Iterator::Locate>, L<Iterator::Simple::Locate>,
L<MooseX::Iterator::Locate>

L<File::Locate>, L<locate(1)>, L<locatedb(5)>, GNU Findutils manual,
L<File::FnMatch>, L<File::Map>

=head1 HOME PAGE

L<http://user42.tuxfamily.org/file-locate-iterator/index.html>

=head1 COPYRIGHT

Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2017, 2018, 2019 Kevin Ryde

File-Locate-Iterator is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3, or (at your option) any
later version.

File-Locate-Iterator is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along with
File-Locate-Iterator.  If not, see http://www.gnu.org/licenses/

=cut