# block until at least <barrier-size> processes of this barrier group entered the barrier
# once this happened, all latecomers will go through immediately!
# WARNING: a barrier group consists of all processes with the same barrier name *and* size!
single-use-barrier() { # <barrier-name> <barrier-size> [<timeout-in-seconds> [<sleep-cycle-time>]]
    local barrier_name="$1"
    local barrier_size="$2"
    local timeout_in_seconds="${3:-0}"
    local sleep_cycle_time="${4:-1}"
    # use name and size to distinguish between invocations
    # this will block inconsistent sizes on the same name!
    local BARRIER_SUFFIX=${barrier_name//\//_}-$barrier_size
    local BARRIER_FILE="$BATS_SUITE_TMPDIR/barrier-$BARRIER_SUFFIX"
    # mark our entry for all others
    # concurrent writes may interleave but should not lose their newlines
    echo "in-$$" >> "$BARRIER_FILE"
    local start="$SECONDS"
    # wait for others to enter
    while [[ $(wc -l <"$BARRIER_FILE" ) -lt $barrier_size ]]; do
        if [[ $timeout_in_seconds -ne 0 && $(( SECONDS - start )) -gt $timeout_in_seconds ]]; then
            mv "$BARRIER_FILE" "$BARRIER_FILE-timeout"
            printf "ERROR: single-use-barrier %s timed out\n" "$BARRIER_SUFFIX" >&2
            return 1
        fi
        sleep "$sleep_cycle_time"
    done
    # mark our exit
    echo "out-$$" >> "$BARRIER_FILE"
}

# block until at least <latch-size> signalling threads have passed the latch
# SINGLE_USE_LATCH_DIR must be exported!
single-use-latch::wait() { # <latch-name> <latch-size> [<timeout-in-seconds> [<sleep-cycle-time>]]
    local latch_name="$1"
    local latch_size="$2"
    local timeout_in_seconds="${3:-0}"
    local sleep_cycle_time="${4:-1}"
    
    local LATCH_FILE
    LATCH_FILE="$(single-use-latch::_filename "$latch_name")"
    local start="$SECONDS"
    while [[ (! -e "$LATCH_FILE") || $(wc -l <"$LATCH_FILE" ) -lt $latch_size ]]; do
        if [[ $timeout_in_seconds -ne 0 && $(( SECONDS - start )) -gt $timeout_in_seconds ]]; then
            printf "ERROR: single-use-latch %s timed out\n" "$latch_name" >&2
            mv "$LATCH_FILE" "$LATCH_FILE-timeout"
            return 1
        fi
        sleep "$sleep_cycle_time"
    done
}

# signal the waiting process that the latch was passed
# this does not block
# SINGLE_USE_LATCH_DIR must be exported!
single-use-latch::signal() { # <latch-name>
    local latch_name="$1"
    local LATCH_FILE
    LATCH_FILE="$(single-use-latch::_filename "$latch_name")"
    # mark our passing
    # concurrent process might interleave but will still post their newline
    echo "passed-$$" >> "$LATCH_FILE"
}

single-use-latch::_filename() { # <latch-name> 
    printf "%s\n" "${SINGLE_USE_LATCH_DIR?}/latch-${1//\//_}"
}