NAME
Data::RecordStore - Simple and fast record based data store
SYNPOSIS
use Data::RecordStore;
my $store = Data::RecordStore->open_store( $directory );
my $data = "TEXT DATA OR BYTES";
my $id = $store->stow( $data, $optionalID );
my $val = $store->fetch( $id );
my $new_or_recycled_id = $store->next_id;
$store->stow( "MORE DATA", $new_or_recycled_id );
my $has_object_at_id = $store->has_id( $someid );
$store->delete( $someid );
$store->empty_recycler; $store->recycle( $dead_id );
DESCRIPTION
A simple and fast way to store arbitrary text or byte data. It is
written entirely in perl with no non-core dependencies. It is designed
to be both easy to set up and easy to use.
LIMITATIONS
Data::RecordStore is not meant to store huge amounts of data. It will
fail if it tries to create a file size greater than the max allowed by
the filesystem. This limitation may be removed in subsequent versions.
This limitation is most important when working with sets of data that
approach the max file size of the system in question.
This is not written with thread safety in mind, so unexpected behavior
can occur when multiple Data::RecordStore objects open the same
directory. Locking coordination is currently the responsibility of the
implementation.
METHODS
open_store( directory )
Takes a single argument - a directory, and constructs the data store in
it. The directory must be writeable or creatible. If a RecordStore
already exists there, it opens it, otherwise it creates a new one.
stow( data, optionalID )
This saves the text or byte data to the record store. If an id is passed
in, this saves the data to the record for that id, overwriting what was
there. If an id is not passed in, it creates a new record store.
Returns the id of the record written to.
fetch( id )
Returns the record associated with the ID. If the ID has no record
associated with it, undef is returned.
entry_count
Returns how many active ids have been assigned in this store. If an ID
was assigned but not used, it still counts towards the number of
entries.
delete( id )
Removes the entry with the given id from the store, freeing up its
space. It does not reuse the id.
has_id( id )
Returns true if an object with this id exists in the record store.
next_id
This sets up a new empty record and returns the id for it.
empty()
This empties out the entire record store completely. Use only if you
mean it.
empty_recycler()
Clears out all data from the recycler
recycle( id, keep_data_flag )
Ads the id to the recycler, so it will be returned when next_id is called.
This removes the data occupied by the id, freeing up space unles keep_data_flag
is set to true.
HELPER PACKAGES
Data::RecordStore relies on two helper packages that are useful in their
own right and are documented here.
HELPER PACKAGE
Data::RecordStore::FixedStore
DESCRIPTION
A fixed record store that uses perl pack and unpack templates to store
identically sized sets of data and uses a single file to do so.
SYNOPSIS
my $template = "LII"; # perl pack template. See perl pack/unpack.
my $size; #required if the template does not have a definite size, like
A*
my $store = Data::RecordStore::FixedStore->open_fixed_store( $template,
$filename, $size );
my $new_id = $store->next_id;
$store->put_record( $id, [ 321421424243, 12, 345 ] );
my $more_data = $store->get_record( $other_id );
my $removed_last = $store->pop;
my $last_id = $store->push( $data_at_the_end );
my $entries = $store->entry_count;
if( $entries < $min ) {
$store->_ensure_entry_count( $min );
}
$store->emtpy;
$store->unlink_store;
METHODS
open_fixed_store( template, filename, size )
Opens or creates the file given as a fixed record length data store. If
a size is not given, it calculates the size from the template, if it
can. This will die if a zero byte record size is determined.
empty
This empties out the database, setting it to zero records.
Returns the number of entries in this store. This is the same as the
size of the file divided by the record size.
get_record( idx )
Returns an arrayref representing the record with the given id. The array
in question is the unpacked template.
next_id
adds an empty record and returns its id, starting with 1
pop
Remove the last record and return it.
last_entry
Return the last record.
push( data )
Add a record to the end of this store. Returns the id assigned to that
record. The data must be a scalar or list reference. If a list
reference, it should conform to the pack template assigned to this
store.
push( idx, data )
Saves the data to the record and the record to the filesystem. The data
must be a scalar or list reference. If a list reference, it should
conform to the pack template assigned to this store.
unlink_store
Removes the file for this record store entirely from the file system.
AUTHOR
Eric Wolf coyocanid@gmail.com
COPYRIGHT AND LICENSE
Copyright (c) 2015-2017 Eric Wolf. All rights reserved. This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
VERSION
Version 2.03 (Nov 21, 2017))