# ***********************************************
# 
# !!!! DO NOT EDIT !!!!
# 
# This file was auto-generated by Build.PL.
# 
# ***********************************************
# 
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

=encoding utf8

=head1 NAME

Lucy::Store::Lock - Abstract class representing an interprocess mutex lock.

=head1 SYNOPSIS

    my $lock = $lock_factory->make_lock(
        name    => 'write',
        timeout => 5000,
    );
    $lock->obtain or die "can't get lock for " . $lock->get_name;
    do_stuff();
    $lock->release;

=head1 DESCRIPTION

The Lock class produces an interprocess mutex lock.  The default subclass
uses dot-lock files, but alternative implementations are possible.

Each lock must have a name which is unique per resource to be locked.  Each
lock also has a “host” id which should be unique per machine; it is used to
help clear away stale locks.

=head1 CONSTRUCTORS

=head2 new

    my $lock = Lucy::Store::Lock->new(
        name     => 'commit',     # required
        folder   => $folder,      # required
        host     => $hostname,    # required
        timeout  => 5000,         # default: 0
        interval => 1000,         # default: 100
    );

Abstract constructor.

=over

=item *

B<folder> - A Folder.

=item *

B<name> - String identifying the resource to be locked, which must
consist solely of characters matching [-_.A-Za-z0-9].

=item *

B<host> - A unique per-machine identifier.

=item *

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

=item *

B<interval> - Time in milliseconds between retries.

=back

=head1 ABSTRACT METHODS

=head2 shared

    my $bool = $lock->shared();

Returns true if the Lock is shared, false if the Lock is exclusive.

=head2 request

    my $bool = $lock->request();

Make one attempt to acquire the lock.

The semantics of L<request()|/request> differ depending on whether L<shared()|/shared> returns
true.  If the Lock is L<shared()|/shared>, then L<request()|/request> should not fail if
another lock is held against the resource identified by
C<name> (though it might fail for other reasons).  If it is
not L<shared()|/shared> – i.e. it’s an exclusive (write) lock – then other locks
should cause L<request()|/request> to fail.

Returns: true on success, false on failure (sets the global error object
returned by Clownfish->error).

=head2 release

    $lock->release();

Release the lock.

=head2 is_locked

    my $bool = $lock->is_locked();

Indicate whether the resource identified by this lock’s name is
currently locked.

Returns: true if the resource is locked, false otherwise.

=head2 clear_stale

    $lock->clear_stale();

Release all locks that meet the following three conditions: the lock
name matches, the host id matches, and the process id that the lock
was created under no longer identifies an active process.

=head1 METHODS

=head2 obtain

    my $bool = $lock->obtain();

Call L<request()|/request> once per C<interval> until L<request()|/request> returns
success or the C<timeout> has been reached.

Returns: true on success, false on failure (sets the global error object
returned by Clownfish->error).

=head1 INHERITANCE

Lucy::Store::Lock isa Clownfish::Obj.

=cut