----------------
O V E R V I E W
----------------

sematree (a semaphore like utility),
formerly known as mutil (a mutex utility),
is a long lived locking utility.

With standard advisory and mandatory locking in POSIX,
the locking is associated with open file descriptors
and hence is automatically removed when a process exits.

So sematree is useful where you want to manipulate locks
across process lifetimes.

sematree allows you to do 4 things with a lock:
acquire, release, inc, dec.

and with these 4 operations you can build up more
complex synchronisation primitives.

----------------
E X A M P L E S
----------------

1. simple mutex to stop 2 instances of a
   script from running at the same time
    --------------------------
    #!/bin/sh
    #myscript

    sematree acquire mylock || exit
    #do stuff
    sematree release mylock
    --------------------------

2. reentrant pair of scripts
    --------------------------
    #!/bin/sh
    #script1
    #do stuff if not done already

    sematree acquire mylock || exit

    num_locks=`sematree inc mylock`
    if [ "$num_locks" -eq "1" ]; then
        #do stuff
    fi

    sematree release mylock
    --------------------------
    #!/bin/sh
    #script2
    #undo stuff if not done already

    sematree acquire mylock || exit

    num_locks=`sematree dec mylock`
    if [ "$num_locks" -eq "0" ]; then
        #undo stuff
    fi

    sematree release mylock
    --------------------------

3. 1 script to wait for another to complete
    --------------------------
    #!/bin/sh
    #asker

    sematree acquire mylock || exit #flag
    #call other script (doer)
    sematree acquire mylock || exit #wait
    sematree release mylock         #finished
    --------------------------
    #!/bin/sh
    #doer

    sematree release mylock #notify waiter(s)
    --------------------------

4. try to acquire lock, but only wait 1 minute.
    --------------------------
    #!/bin/sh
    #myscript

    sematree acquire mylock 60 || exit
    #do stuff
    sematree release mylock
    --------------------------

5. try to acquire lock, but only wait 1 minute,
   and give error message if can't acquire.
    --------------------------
    #!/bin/sh
    #myscript

    sematree acquire mylock 60
    if [ $? != 0 ]; then
        echo "couldn't acquire lock, aborting..." >&2
        exit 1
    fi
    #do stuff
    sematree release mylock
    --------------------------