# Auto-generated file -- DO NOT EDIT!!!!!

=head1 NAME

KinoSearch::Store::SharedLock - Shared (read) lock.

=head1 SYNOPSIS

    my $lock_factory = KinoSearch::Store::LockFactory->new(
        folder    => $folder,
        agent_id  => $hostname,
    );
    my $shlock = $lock_factory->make_shared_lock(
        lock_name => 'snapshot_6r',
        timeout   => 5000,
    );



=head1 DESCRIPTION

SharedLock's interface is nearly identical to that of its parent class
L<KinoSearch::Store::Lock>, taking the same constructor arguments and
implementing the same list of methods.  It differs from Lock only in the
semantics of two methods.

First, obtain() will not fail if another lock is held against the resource
identified by C<< lock_name >> (though it might fail for other
reasons).

Second, is_locked() returns true so long as some lock, somewhere is holding
a lock on C<< lock_name >>.  That lock could be this instance, or it
could be another -- so is entirely possible to call release() successfully
on a SharedLock object yet still have is_locked() return true.

As currently implemented, SharedLock differs from Lock in that each caller
gets its own lockfile.  Lockfiles still have filenames which begin with the
lock name and end with ".lock", but each is also assigned a unique number
which gets pasted between: "foo-44.lock" instead of "foo.lock".  A
SharedLock is considered fully released when no lock files with a given
lock name are left.

=head1 CONSTRUCTORS

=head2 new( I<[labeled params]> )

    my $shlock = KinoSearch::Store::SharedLock->new(
        lock_name => 'commit',           # required
        timeout   => 5000,               # default: 0
        folder    => $folder,            # required
        agent_id  => $hostname,          # required
    );

=over

=item *

B<folder> - The KinoSearch::Store::Folder where the lock file will
reside.

=item *

B<lock_name> - String identifying the resource to be locked.

=item *

B<agent_id> - A per-machine identifier, usually the host name.

=item *

B<timeout> - Time in milliseconds to keep retrying before abandoning
the attempt to obtain() a lock.

=back







=head1 INHERITANCE

KinoSearch::Store::SharedLock isa L<KinoSearch::Store::Lock> isa L<KinoSearch::Obj>.


=head1 COPYRIGHT

Copyright 2005-2009 Marvin Humphrey

=head1 LICENSE, DISCLAIMER, BUGS, etc.

See L<KinoSearch> version 0.30.

=cut