[dbsrgits/DBM-Deep.git] / lib / DBM / Deep / Storage.pm

package DBM::Deep::Storage;

use 5.006_000;

use strict;
use warnings FATAL => 'all';

=head2 flush()

This flushes the filehandle. This takes no parameters and returns nothing.

=cut

sub flush { die "flush must be implemented in a child class" }

=head2 is_writable()

This takes no parameters. It returns a boolean saying if this filehandle is
writable.

Taken from L<http://www.perlmonks.org/?node_id=691054/>.

=cut

sub is_writable { die "is_writable must be implemented in a child class" }

=head1 LOCKING

This is where the actual locking of the storage medium is performed.
Nested locking is supported.

B<NOTE>: It is unclear what will happen if a read lock is taken, then
a write lock is taken as a nested lock, then the write lock is released.

Currently, the only locking method supported is flock(1). This is a
whole-file lock. In the future, more granular locking may be supported.
The API for that is unclear right now.

The following methods manage the locking status. In all cases, they take
a L<DBM::Deep> object and returns nothing.

=over 4

=item * lock_exclusive( $obj )

Take a lock usable for writing.

=item * lock_shared( $obj )

Take a lock usable for reading.

=item * unlock( $obj )

Releases the last lock taken. If this is the outermost lock, then the
object is actually unlocked.

=back

=cut

sub lock_exclusive { die "lock_exclusive must be implemented in a child class" }
sub lock_shared { die "lock_shared must be implemented in a child class" }
sub unlock { die "unlock must be implemented in a child class" }

1;
__END__
Commit	Line	Data
2c70efe1	1	package DBM::Deep::Storage;
	2
	3	use 5.006_000;
	4
	5	use strict;
	6	use warnings FATAL => 'all';
	7
	8	=head2 flush()
	9
	10	This flushes the filehandle. This takes no parameters and returns nothing.
	11
	12	=cut
	13
	14	sub flush { die "flush must be implemented in a child class" }
	15
	16	=head2 is_writable()
	17
	18	This takes no parameters. It returns a boolean saying if this filehandle is
	19	writable.
	20
	21	Taken from L<http://www.perlmonks.org/?node_id=691054/>.
	22
	23	=cut
	24
	25	sub is_writable { die "is_writable must be implemented in a child class" }
	26
	27	=head1 LOCKING
	28
	29	This is where the actual locking of the storage medium is performed.
	30	Nested locking is supported.
	31
	32	B<NOTE>: It is unclear what will happen if a read lock is taken, then
	33	a write lock is taken as a nested lock, then the write lock is released.
	34
	35	Currently, the only locking method supported is flock(1). This is a
	36	whole-file lock. In the future, more granular locking may be supported.
	37	The API for that is unclear right now.
	38
	39	The following methods manage the locking status. In all cases, they take
1c62d370	40	a L<DBM::Deep> object and returns nothing.
2c70efe1	41
	42	=over 4
	43
	44	=item * lock_exclusive( $obj )
	45
	46	Take a lock usable for writing.
	47
	48	=item * lock_shared( $obj )
	49
	50	Take a lock usable for reading.
	51
	52	=item * unlock( $obj )
	53
	54	Releases the last lock taken. If this is the outermost lock, then the
	55	object is actually unlocked.
	56
	57	=back
	58
	59	=cut
	60
	61	sub lock_exclusive { die "lock_exclusive must be implemented in a child class" }
	62	sub lock_shared { die "lock_shared must be implemented in a child class" }
	63	sub unlock { die "unlock must be implemented in a child class" }
	64
	65	1;
	66	__END__