---
name: "Lucy::Store::Lock"
section: "3pm"
platform: "linux"
package: "liblucy-perl"
version: "0.3.3-7+b1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/Lucy::Store::Lock"
---

# Lucy::Store::Lock(3pm)

Abstract class representing an interprocess mutex lock.

## NAME

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

## 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;
```

## 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.

## CONSTRUCTORS

### new( *\[labeled params\]* )

```
    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.

- •

  **folder** - A Folder.

- •

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

- •

  **host** - A unique per-machine identifier.

- •

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

- •

  **interval** - Time in milliseconds between retries.

## ABSTRACT METHODS

### *request()*

Make one attempt to acquire the lock.

The semantics of *request()* differ depending on whether *shared()* returns true.  If the Lock is *shared()*, then *request()* should not fail if another lock is held against the resource identified by `"name"` (though it might fail for other reasons).  If it is not *shared()* -- i.e. it's an exclusive (write) lock -- then other locks should cause *request()* to fail.

Returns: true on success, false on failure (sets Lucy-\>error).

### *release()*

Release the 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.

### *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.

## METHODS

### *obtain()*

Call *request()* once per `"interval"` until *request()* returns success or the `"timeout"` has been reached.

Returns: true on success, false on failure (sets Lucy-\>error).

## INHERITANCE

Lucy::Store::Lock isa Lucy::Object::Obj.