[1mNAME[0m
     Data::RecordStore - Simple store for text and byte data

[1mSYNPOSIS[0m
     use Data::RecordStore;

     $store = Data::RecordStore->open_store( $directory );
     $data = "TEXT OR BYTES";

     # the first record id is 1
     my $id = $store->stow( $data );

     my $new_or_recycled_id = $store->next_id;
     $store->stow( $new_data, $new_or_recycled_id );

     my $val = $store->fetch( $some_id );

     my $count = $store->entry_count;

     # delete the old record, make its id available for future
     # records
     $store->recycle_id( $id_to_recycle ); 

     $store->delete_record( $id_to_remove ); #deletes the old record

     my $has_id = $store->has_id( $someother_id );

     $store->empty; # clears out store completely

[1mDESCRIPTION[0m
    Data::RecordStore is a simple way to store serialized 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. Space is automatically
    reclaimed when records are reycled or deleted.

    Transactions (see below) can be created that stow and recycle records.
    They come with the standard commit and rollback methods. If a process dies
    in the middle of a commit or rollback, the operation can be reattempted.
    Incomplete transactions are obtained by the store's 'list_transactions'
    method.

    Data::RecordStore operates directly and instantly on the file system. It
    is not a daemon or server and is not thread safe. It can be used in a
    thread safe manner if the controlling program uses locking mechanisms.

[1mMETHODS[0m
  [1mopen_store( directory, options )[0m
    Takes 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.

   Options
    group - when files are created, they use this user group if able.

  [1mcreate_transaction()[0m
    Creates and returns a transaction object

  [1mlist_transactions[0m
    Returns a list of currently existing transaction objects not marked
    TRA_DONE.

  [1mstow( data, optionalID )[0m
    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.

  [1mfetch( id )[0m
    Returns the record associated with the ID. If the ID has no record
    associated with it, undef is returned.

  [1mentry_count[0m
    How many entries there are for records. This is equal to the highest ID
    that has been assigned minus the number of pending recycles. It is
    different from the record count, as entries may be marked deleted.

  [1mrecord_count[0m
    Return how many records there actually are

  [1mdelete_record( id )[0m
    Removes the entry with the given id from the store, freeing up its space.
    It does not reuse the id.

  [1mhas_id( id )[0m
      Returns true if an record with this id exists in the record store.

  [1mnext_id[0m
    This sets up a new empty record and returns the id for it.

  [1mempty()[0m
    This empties out the entire record store completely. Use only if you mean
    it.

  [1mempty_recycler()[0m
      Clears out all data from the recycler.

  [1mrecycle( id, keep_data_flag )[0m
      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.

[1mLIMITATIONS[0m
    Data::RecordStore is not thread safe. Thread coordination and locking can
    be done on a level above Data::RecordStore.

[1mHELPER PACKAGE[0m
    Data::RecordStore::Transaction

[1mHELPER DESCRIPTION[0m
    A transaction that can collect actions on the record store and then writes
    them as a block.

[1mHELPER SYNOPSIS[0m
    my $transaction = $store->create_transaction;

    print join(",", $transaction->get_update_time,
    $transaction->get_process_id, $transaction->get_state,
    $transaction->get_id );

    my $new_id = $transaction->stow( $data );

    my $new_or_recycled_id = $store->next_id;

    $transaction->stow( "MORE DATA", $new_or_recycled_id );

    $transaction->delete_record( $someid ); $transaction->recycle_id( $dead_id
    );

    if( $is_good ) { $transaction->commit; } else { $transaction->rollback; }

    # # Get a list of transactions that are old and probably stale. # for my
    $trans ($store->list_transactions) {

      next if $trans->get_udpate_time > $too_old;

      my $state = $trans->get_state;
      if( $state == Data::RecordStore::Transaction::TRA_IN_COMMIT
        || $state == Data::RecordStore::Transaction::TRA_CLEANUP_COMMIT )
      {
         $trans->commit;
      }
      elsif( $state == Data::RecordStore::Transaction::TRA_IN_ROLLBACK
        || $state == Data::RecordStore::Transaction::TRA_CLEANUP_ROLLBACK )
      {
         $trans->rollback;
      }
      elsif( $state == Data::RecordStore::Transaction::TRA_ACTIVE )
      {
         # commit or rollback, depending on preference
      }
    }

[1mMETHODS[0m
  [1mget_update_time[0m
    Returns the epoch time when the last time this was updated.

  [1mget_process_id[0m
    Returns the process id that last wrote to this transaction.

  [1mget_state[0m
    Returns the state of this process. Values are TRA_ACTIVE TRA_IN_COMMIT
    TRA_IN_ROLLBACK TRA_COMMIT_CLEANUP TRA_ROLLBACK_CLEANUP TRA_DONE

  [1mget_id[0m
    Returns the ID for this transaction, which is the same as its position in
    the transaction index plus one.

  [1mstow( $data, $optional_id )[0m
    Stores the data given. Returns the id that the data was stowed under. If
    the id is not given, this generates one from the record store. The data
    stored this way is really stored in the record store, but the index is not
    updated until a commit happens. That means it is not reachable from the
    store until the commit.

  [1mdelete_record( $id )[0m
    Marks that the record associated with the id is to be deleted when the
    transaction commits.

  [1mrecycle_id( $id )[0m
    Marks that the record associated with the id is to be deleted and its id
    recycled when the transaction commits.

  [1mcommit()[0m
    Commit applies

  [1munlink_store[0m
    Removes the file for this record store entirely from the file system.

[1mAUTHOR
       Eric Wolf        coyocanid@gmail.com[0m
[1mCOPYRIGHT AND LICENSE[0m
           Copyright (c) 2015-2018 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.

[1mVERSION
       Version 3.23  (Sep, 2018))[0m
