# tlock

### Locking with timeouts.

tlock is handling "tlocks", advisory locks with timeouts.

They are implemented as simple directories that are created and deleted in the lock directory.

A distant predecessor was written many years ago as a kludge to make locking work properly on a Windows server. But it turned out to be very handy to have tlocks in the filesystem, giving you an at-a-glance overview of them. And giving the non-scripting sysadmins easy access to view and manipulate tlocks.

    # taking a tlock for 5 minutes
    token=$(tlock take 'logwork' 300 || exit 1)

    move_old_index

    # hand over to that other script
    /usr/local/logrotate/logrotate $token

    -----------------------------------------------------------

    # checking lock is alive
    token=$1
    tlock alive 'logwork' $token || exit 1

    # Make time for the fancy rotation task.
    tlock renew 'logwork' 600

    do_fancy_log_rotation 547
    /usr/local/cleaning/clean-up-logs.sh $token

    # releasing the lock
    tlock release 'logwork' $token

## Configuration

There are a number of ways tlock parameters can be set, The prioritized list is:

1. Directly on the command line with options "-d", "-m" and "-p".

1. Environment variables "tlock_dir", "tlock_marker" and "tlock_patience".

1. Configuration file given by the environment variable "tlock_conf".

1. Configuration file "/etc/tlock.conf".

1. Default configuration.

## In the file system

Each tlock is a subdirectory of the lock directory. Their names are "$marker.$label". The default value for $marker is "tlock".

Each of the tlock directories has a sub directory named "d". The mtimes of these two directories saves the token and the timeout.
There also are some very shortlived directories named "$marker_.$label". They are per label master locks. They help making changes to the normal locks atomic.

## Command line

tlock [-<option> [parameter]] <command> [parameter ...]

## Options

-d <d>  Set the lock directory to <d>.

-h      Show help text.

-m <m>  Set marker to <m>.

-p <p>  Set patience to <p>.

-V      Show the version.

## Commands

**tlock take <label> <timeout> [<patience>]**

Takes the specified tlock if possible. Returns the token value.

**tlock renew <label> <token> <timeout>**

Renews the tlock.

**tlock release <label> <token>**

Releases the tlock.

**tlock alive <label> <token>**

Returns true if the specified tlock is still alive.

**tlock taken <label>**

Returns true if any tlock with the given label, is alive.

**tlock expiry <label>**

Returns the time when the tlock with the given label will expire.

**tlock zing**

Cleans up the lock directory.

## Parameters

**dir**

The directory containing the tlocks.

**marker**

The common prefix of the directory names used for tlocks.

Prefixes can be any non-empty string consisting of letters a-z or A-Z, digits 0-9, dashes "-" and underscores "_" (PCRE: [a-zA-Z0-9\-\_]+). First character has to be a letter, and last character a letter or digit.

**patience**

Patience is the time a method will try to take or change a tlock, before it gives up. For example when tlock_take tries to take a tlock that is already taken, it is the number of seconds it should wait for that tlock to be released before giving up.

Default patience value is 2.5 seconds.,

## One tlock, multiple scripts

The point of having tokens is to be able to hand over locks between scripts in a secure way. These scripts can be written in different languages. But they have to use the same dir and marker settings.

If you are using Perl there is a module available. You can read more here: [https://github.com/spragl/Tlock/blob/main/PERL.md](https://github.com/spragl/Tlock/blob/main/PERL.md)

## License & copyright

(c) 2022-2023 Bjoern Hee

Licensed under the Apache License, version 2.0

https://www.apache.org/licenses/LICENSE-2.0.txt