X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBM%2FDeep.pod;h=7252f7c5b1855f447080b91ec2dcd42b98f1b3fe;hb=5c0756fcb3b5c7ca76c52be6c7c9d78841e5d57b;hp=6b5b2e64fcbed7ba0fdefb26e82e9fac8a090796;hpb=c57b19c6ae9b7bd8b23581479afa8664d69023b2;p=dbsrgits%2FDBM-Deep.git
diff --git a/lib/DBM/Deep.pod b/lib/DBM/Deep.pod
index 6b5b2e6..7252f7c 100644
--- a/lib/DBM/Deep.pod
+++ b/lib/DBM/Deep.pod
@@ -99,7 +99,7 @@ the wrong type is passed in.
Alternately, you can create a DBM::Deep handle by using Perl's built-in
tie() function. The object returned from tie() can be used to call methods,
such as lock() and unlock(). (That object can be retrieved from the tied
-variable at any time using tied() - please see L for more info.
+variable at any time using tied() - please see L for more info.
my %hash;
my $db = tie %hash, "DBM::Deep", "foo.db";
@@ -385,18 +385,28 @@ value.
$db->clear(); # hashes or arrays
-=item * lock() / unlock()
+=item * lock_exclusive() / lock_shared() / lock() / unlock()
-q.v. Locking.
+q.v. L for more info.
=item * optimize()
-Recover lost disk space. This is important to do, especially if you use
-transactions.
+This will compress the datafile so that it takes up as little space as possible.
+There is a freespace manager so that when space is freed up, it is used before
+extending the size of the datafile. But, that freespace just sits in the datafile
+unless C is called.
-=item * import() / export()
+=item * import()
-Data going in and out.
+Unlike simple assignment, C does not tie the right-hand side. Instead,
+a copy of your data is put into the DB. C takes either an arrayref (if
+your DB is an array) or a hashref (if your DB is a hash). C will die
+if anything else is passed in.
+
+=item * export()
+
+This returns a complete copy of the data structure at the point you do the export.
+This copy is in RAM, not on disk like the DB is.
=item * begin_work() / commit() / rollback()
@@ -562,15 +572,14 @@ then incremented, then stored again.
$db->{counter}++;
$db->unlock();
-You can pass C an optional argument, which specifies which mode to use
-(exclusive or shared). Use one of these two constants:
-CLOCK_EX> or CLOCK_SH>. These are passed
-directly to C, and are the same as the constants defined in Perl's
-L module.
+If you want a shared lock, you will need to call C. C is
+an alias to C.
- $db->lock( $db->LOCK_SH );
- # something here
- $db->unlock();
+=head2 Win32/Cygwin
+
+Due to Win32 actually enforcing the read-only status of a shared lock, all
+locks on Win32 and cygwin are exclusive. This is because of how autovivification
+currently works. Hopefully, this will go away in a future release.
=head1 IMPORTING/EXPORTING
@@ -702,7 +711,7 @@ remove a filter, set the function reference to C:
=head2 Examples
-Please read L for examples of filters.
+Please read L for examples of filters.
=head1 ERROR HANDLING
@@ -854,7 +863,7 @@ immediately, please submit many testcases.
=head2 Caching
-If a user is willing to assert upon opening the file that this process will be
+If a client is willing to assert upon opening the file that this process will be
the only consumer of that datafile, then there are a number of caching
possibilities that can be taken advantage of. This does, however, mean that
DBM::Deep is more vulnerable to losing data due to unflushed changes. It also
@@ -869,13 +878,6 @@ substr, the STM capabilities of DBM::Deep could be used within a
single-process. I have no idea how I'd specify this, though. Suggestions are
welcome.
-=head2 Importing using Data::Walker
-
-Right now, importing is done using C to make a complete copy
-in memory, then tying that copy. It would be much better to use
-L to walk the data structure instead, particularly in the case
-of large datastructures.
-
=head2 Different contention resolution mechanisms
Currently, the only contention resolution mechanism is last-write-wins. This
@@ -936,7 +938,7 @@ all to support a feature that has never been requested.
=item * CODE
-L provides a mechanism for serializing coderefs,
+L provides a mechanism for serializing coderefs,
including saving off all closure state. This would allow for DBM::Deep to
store the code for a subroutine. Then, whenever the subroutine is read, the
code could be C'ed into being. However, just as for SCALAR and REF,
@@ -991,12 +993,17 @@ These functions cause every element in the array to move, which can be murder
on DBM::Deep, as every element has to be fetched from disk, then stored again in
a different location. This will be addressed in a future version.
+This has been somewhat addressed so that the cost is constant, regardless of
+what is stored at those locations. So, small arrays with huge data structures in
+them are faster. But, large arrays are still large.
+
=head2 Writeonly Files
-If you pass in a filehandle to new(), you may have opened it in either a readonly or
-writeonly mode. STORE will verify that the filehandle is writable. However, there
-doesn't seem to be a good way to determine if a filehandle is readable. And, if the
-filehandle isn't readable, it's not clear what will happen. So, don't do that.
+If you pass in a filehandle to new(), you may have opened it in either a
+readonly or writeonly mode. STORE will verify that the filehandle is writable.
+However, there doesn't seem to be a good way to determine if a filehandle is
+readable. And, if the filehandle isn't readable, it's not clear what will
+happen. So, don't do that.
=head2 Assignments Within Transactions
@@ -1021,18 +1028,18 @@ reference to be imported in order to explicitly leave it untied.
=head1 CODE COVERAGE
-B is used to test the code coverage of the tests. Below is the
-B report on this distribution's test suite.
+L is used to test the code coverage of the tests. Below is the
+L report on this distribution's test suite.
------------------------------------------ ------ ------ ------ ------ ------
File stmt bran cond sub total
------------------------------------------ ------ ------ ------ ------ ------
- blib/lib/DBM/Deep.pm 96.9 88.3 90.5 100.0 95.7
+ blib/lib/DBM/Deep.pm 97.2 90.9 83.3 100.0 95.4
blib/lib/DBM/Deep/Array.pm 100.0 95.7 100.0 100.0 99.0
- blib/lib/DBM/Deep/Engine.pm 95.5 84.7 81.6 98.4 92.4
+ blib/lib/DBM/Deep/Engine.pm 95.6 84.7 81.6 98.4 92.5
blib/lib/DBM/Deep/File.pm 97.2 81.6 66.7 100.0 91.9
blib/lib/DBM/Deep/Hash.pm 100.0 100.0 100.0 100.0 100.0
- Total 96.7 87.0 83.3 99.2 94.1
+ Total 96.7 87.5 82.2 99.2 94.1
------------------------------------------ ------ ------ ------ ------ ------
=head1 MORE INFORMATION