# What is Locker?

Locker is a simple, platform-independent PHP class for mutual exclusive locking
(mutex). It helps you ensure that a particular resource can only be used by one
thread at a time, which is especially important when running a script on a regular basis and there might be a chance that a run starts before the previous has been finished completely.

The locking is done by simply creating a directory at a certain location via `mkdir` command. This command would fail if the directory already existed. On the other hand, if it succeeds the creation is done in a single atomic action, so it cannot cause any race conditions.


## Basic Usage

First, you have to prepare an empty directory which is writable for PHP scripts.
Let's say, the path is stored in a variable called `$lockDir`, then do the
following:

```php
require_once 'locker.class.php';
$locker = new Locker( $lockDir );

if ( ! $locker->get_lock('myProcess') )
{
   die('Could not get lock');
}

// do some work

$locker->release_lock('myProcess');
```

## Avoiding Infinite Locks

Even if you forget to call the `release_lock` method, all locks created by the
current script will be removed automatically on shutdown. But when there is a
power failure, or the script gets killed or crashes, the locks would remain
forever, blocking any subsequent attempts to get exclusive access to the locked
resources. In order to avoid this scenario, Locker has an automatic unlock
feature. 

By default, when trying to lock a resource, an existing lock is ignored if it is
older than 24 hours. You can adjust this "auto unlock period" by providing a
second parameter when calling the `get_lock` method:

```php
if ( ! $locker->get_lock( 'myProcess', 180 ) )
{
   die('Could not get lock although ignoring locks older than 3 minutes)');
}
```

Alternatively, you may set the `autoUnlockPeriod` property of the Locker object
to the desired number of seconds:

```php
$locker->autoUnlockPeriod = 180;
```

You should carefully consider which auto unlock period is suitable for your
project. If it is too short, there might be occasions when a lock gets
auto-removed although the originating script is still running. If it is too
long, certain functions of your application might be blocked unneccessarily long
after a crash. 


## Changing the Time-Out

If a lock cannot be obtained, Locker will wait a second, then retry, then wait
another second, retry etc. By default this trial process lasts five seconds,
after which Locker will give up. If you want a shorter or longer time-out
period, you may set the desired number of seconds as third parameter when
calling the `get_lock` method:

```php
if ( ! $locker->get_lock( 'myProcess', 180, 10 ) )
{
   die('Could not get lock in 10 seconds');
}
```

Alternatively, you may set the `timeOutPeriod` property of the Locker object to
the desired number of seconds:

```php
$locker->timeOutPeriod = 10;
```

Don't worry too much about the time-out period. It can make your application a
little bit more user-friendly but is irrelevant, if you run your scripts via cron
jobs. From a user's point of view it is just less annoying to wait some seconds
for a reponse than to get an error message.