dbm::deep::storage::file(3pm) [debian man page]
DBM::Deep::Storage::File(3pm) User Contributed Perl Documentation DBM::Deep::Storage::File(3pm) NAME
DBM::Deep::Storage::File - mediate low-level interaction with storage mechanism PURPOSE
This is an internal-use-only object for DBM::Deep. It mediates the low-level interaction with the storage mechanism. Currently, the only storage mechanism supported is the file system. OVERVIEW
This class provides an abstraction to the storage mechanism so that the Engine (the only class that uses this class) doesn't have to worry about that. METHODS
new( \%args ) open() This method opens the filehandle for the filename in " file ". There is no return value. close() If the filehandle is opened, this will close it. There is no return value. size() This will return the size of the DB. If file_offset is set, this will take that into account. NOTE: This function isn't used internally anywhere. set_inode() This will set the inode value of the underlying file object. This is only needed to handle some obscure Win32 bugs. It reqlly shouldn't be needed outside this object. There is no return value. print_at( $offset, @data ) This takes an optional offset and some data to print. $offset , if defined, will be used to seek into the file. If file_offset is set, it will be used as the zero location. If it is undefined, no seeking will occur. Then, @data will be printed to the current location. There is no return value. read_at( $offset, $length ) This takes an optional offset and a length. $offset , if defined, will be used to seek into the file. If file_offset is set, it will be used as the zero location. If it is undefined, no seeking will occur. Then, $length bytes will be read from the current location. The data read will be returned. DESTROY When the ::Storage::File object goes out of scope, it will be closed. request_space( $size ) This takes a size and adds that much space to the DBM. This returns the offset for the new location. copy_stats( $target_filename ) This will take the stats for the current filehandle and apply them to $target_filename . The stats copied are: o Onwer UID and GID o Permissions perl v5.14.2 2012-06-24 DBM::Deep::Storage::File(3pm)
Check Out this Related Man Page
DBM::Deep::Cookbook(3pm) User Contributed Perl Documentation DBM::Deep::Cookbook(3pm) NAME
DBM::Deep::Cookbook - Cookbook for DBM::Deep DESCRIPTION
This is the Cookbook for DBM::Deep. It contains useful tips and tricks, plus some examples of how to do common tasks. RECIPES
Unicode data If possible, it is highly recommended that you upgrade your database to version 2 (using the utils/upgrade_db.pl script in the CPAN distribution), in order to use Unicode. If your databases are still shared by perl installations with older DBM::Deep versions, you can use filters to encode strings on the fly: my $db = DBM::Deep->new( ... ); my $encode_sub = sub { my $s = shift; utf8::encode($s); $s }; my $decode_sub = sub { my $s = shift; utf8::decode($s); $s }; $db->set_filter( 'store_value' => $encode_sub ); $db->set_filter( 'fetch_value' => $decode_sub ); $db->set_filter( 'store_key' => $encode_sub ); $db->set_filter( 'fetch_key' => $decode_sub ); A previous version of this cookbook recommended using "binmode $db->_fh, ":utf8"", but that is not a good idea, as it could easily corrupt the database. Real-time Encryption Example NOTE: This is just an example of how to write a filter. This most definitely should NOT be taken as a proper way to write a filter that does encryption. (Furthermore, it fails to take Unicode into account.) Here is a working example that uses the Crypt::Blowfish module to do real-time encryption / decryption of keys & values with DBM::Deep Filters. Please visit <http://search.cpan.org/search?module=Crypt::Blowfish> for more on Crypt::Blowfish. You'll also need the Crypt::CBC module. use DBM::Deep; use Crypt::Blowfish; use Crypt::CBC; my $cipher = Crypt::CBC->new({ 'key' => 'my secret key', 'cipher' => 'Blowfish', 'iv' => '$KJh#(}q', 'regenerate_key' => 0, 'padding' => 'space', 'prepend_iv' => 0 }); my $db = DBM::Deep->new( file => "foo-encrypt.db", filter_store_key => &my_encrypt, filter_store_value => &my_encrypt, filter_fetch_key => &my_decrypt, filter_fetch_value => &my_decrypt, ); $db->{key1} = "value1"; $db->{key2} = "value2"; print "key1: " . $db->{key1} . " "; print "key2: " . $db->{key2} . " "; undef $db; exit; sub my_encrypt { return $cipher->encrypt( $_[0] ); } sub my_decrypt { return $cipher->decrypt( $_[0] ); } Real-time Compression Example Here is a working example that uses the Compress::Zlib module to do real-time compression / decompression of keys & values with DBM::Deep Filters. Please visit <http://search.cpan.org/search?module=Compress::Zlib> for more on Compress::Zlib. use DBM::Deep; use Compress::Zlib; my $db = DBM::Deep->new( file => "foo-compress.db", filter_store_key => &my_compress, filter_store_value => &my_compress, filter_fetch_key => &my_decompress, filter_fetch_value => &my_decompress, ); $db->{key1} = "value1"; $db->{key2} = "value2"; print "key1: " . $db->{key1} . " "; print "key2: " . $db->{key2} . " "; undef $db; exit; sub my_compress { my $s = shift; utf8::encode($s); return Compress::Zlib::memGzip( $s ) ; } sub my_decompress { my $s = Compress::Zlib::memGunzip( shift ) ; utf8::decode($s); return $s; } Note: Filtering of keys only applies to hashes. Array "keys" are actually numerical index numbers, and are not filtered. Custom Digest Algorithm DBM::Deep by default uses the Message Digest 5 (MD5) algorithm for hashing keys. However you can override this, and use another algorithm (such as SHA-256) or even write your own. But please note that DBM::Deep currently expects zero collisions, so your algorithm has to be perfect, so to speak. Collision detection may be introduced in a later version. You can specify a custom digest algorithm by passing it into the parameter list for new(), passing a reference to a subroutine as the 'digest' parameter, and the length of the algorithm's hashes (in bytes) as the 'hash_size' parameter. Here is a working example that uses a 256-bit hash from the Digest::SHA256 module. Please see <http://search.cpan.org/search?module=Digest::SHA256> for more information. The value passed to your digest function will be encoded as UTF-8 if the database is in version 2 format or higher. use DBM::Deep; use Digest::SHA256; my $context = Digest::SHA256::new(256); my $db = DBM::Deep->new( filename => "foo-sha.db", digest => &my_digest, hash_size => 32, ); $db->{key1} = "value1"; $db->{key2} = "value2"; print "key1: " . $db->{key1} . " "; print "key2: " . $db->{key2} . " "; undef $db; exit; sub my_digest { return substr( $context->hash($_[0]), 0, 32 ); } Note: Your returned digest strings must be EXACTLY the number of bytes you specify in the hash_size parameter (in this case 32). Undefined behavior will occur otherwise. Note: If you do choose to use a custom digest algorithm, you must set it every time you access this file. Otherwise, the default (MD5) will be used. PERFORMANCE
Because DBM::Deep is a conncurrent datastore, every change is flushed to disk immediately and every read goes to disk. This means that DBM::Deep functions at the speed of disk (generally 10-20ms) vs. the speed of RAM (generally 50-70ns), or at least 150-200x slower than the comparable in-memory datastructure in Perl. There are several techniques you can use to speed up how DBM::Deep functions. o Put it on a ramdisk The easiest and quickest mechanism to making DBM::Deep run faster is to create a ramdisk and locate the DBM::Deep file there. Doing this as an option may become a feature of DBM::Deep, assuming there is a good ramdisk wrapper on CPAN. o Work at the tightest level possible It is much faster to assign the level of your db that you are working with to an intermediate variable than to re-look it up every time. Thus # BAD while ( my ($k, $v) = each %{$db->{foo}{bar}{baz}} ) { ... } # GOOD my $x = $db->{foo}{bar}{baz}; while ( my ($k, $v) = each %$x ) { ... } o Make your file as tight as possible If you know that you are not going to use more than 65K in your database, consider using the "pack_size => 'small'" option. This will instruct DBM::Deep to use 16bit addresses, meaning that the seek times will be less. SEE ALSO
DBM::Deep(3), Digest::MD5(3), Digest::SHA256(3), Crypt::Blowfish(3), Compress::Zlib(3) perl v5.14.2 2012-06-24 DBM::Deep::Cookbook(3pm)