Changed everything around so that we're releasing 1.0003, not 1.0009_01. Plus, update...

[dbsrgits/DBM-Deep.git] / lib / DBM / Deep / Cookbook.pod

diff --git a/lib/DBM/Deep/Cookbook.pod b/lib/DBM/Deep/Cookbook.pod
index b82ad8a..7c62c16 100644 (file)
--- a/lib/DBM/Deep/Cookbook.pod
+++ b/lib/DBM/Deep/Cookbook.pod
@@ -28,6 +28,10 @@ L<DBM::Deep/> will do these things for you.
 
 =head2 Real-time Encryption Example
 
+B<NOTE>: This is just an example of how to write a filter. This most
+definitely should B<NOT> be taken as a proper way to write a filter that does
+encryption.
+
 Here is a working example that uses the I<Crypt::Blowfish> module to
 do real-time encryption / decryption of keys & values with DBM::Deep Filters.
 Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more
@@ -150,4 +154,46 @@ behavior will occur otherwise.
 B<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.
 
+=head1 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.
+
+=over 4
+
+=item * 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.
+
+=item * 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 ) {
+    ...
+  }
+
+=item * 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 C<pack_size =E<gt> 'small'> option. This will instruct
+DBM::Deep to use 16bit addresses, meaning that the seek times will be less.
+
+=back
+
 =cut