five/hbrdd/dbf/locks_posix.go

// Copyright (c) 2026 Charles KWON OhJun (charleskwonohjun@gmail.com)
// All rights reserved.

//go:build !windows

// POSIX file locking (fcntl byte-range locks) for DBF shared mode.
// Equivalent to Harbour's hb_fsLockLarge / F_SETLK implementation.
//
// We use POSIX advisory byte-range locks (F_SETLK / F_SETLKW) rather than
// flock(2) because:
//   1. Byte-range granularity is required for record-level DBRLOCK semantics
//   2. POSIX fcntl locks work across NFS (flock does not)
//   3. Harbour and Clipper both use this exact mechanism on *nix
//
// Lock regions (compatible with Harbour's NETIO layout):
//   - FLOCK (whole-file exclusive): high byte in 32-bit range, len = large
//   - DBRLOCK (single record): at RecordOffset(n), len = RecordLen
//
// The high-offset file lock avoids overlapping with record locks so that
// both can coexist on the same file descriptor.

package dbf

import (
	"fmt"
	"syscall"
	"time"
)

// flockAll acquires/releases an exclusive lock on the DBF header area.
// We use offset 0, length = HeaderLen + 1 so that:
//   - FLOCK blocks all writers that would touch the header
//   - Record locks (at RecordOffset(n), past the header) don't conflict
const flockOffset = int64(0)

// appendLockOffset is the byte range used to serialize concurrent
// APPEND across processes. We park it well above any realistic 32-bit
// DBF record offset so it doesn't collide with FLOCK (header) or
// record locks. POSIX fcntl allows locking byte ranges past EOF.
// Harbour's protocol uses an equivalent special offset for append.
const appendLockOffset = int64(0x7FFFFFFE)
const appendLockLen = int64(1)

func flockLen(a *DBFArea) int64 {
	return int64(a.header.HeaderLen) + 1
}

// lockAppendIntent acquires the append-intent lock with bounded
// retries. Without serialization, two processes simultaneously
// running APPEND would both read the same `recCount` from the
// header, write at the same RecordOffset, and one record would
// silently overwrite the other.
//
// The retry budget is intentionally short — append contention is
// usually a few hundred microseconds, so a long block here is the
// signal of a misbehaving peer rather than legitimate competition.
func (a *DBFArea) lockAppendIntent() error {
	if a.dataFile == nil {
		return fmt.Errorf("file not open")
	}
	fd := int(a.dataFile.Fd())
	deadline := 100 // ~100 ms total (1 ms × 100); cheap bound vs blocking F_SETLKW
	for i := 0; i < deadline; i++ {
		ok, err := tryLock(fd, appendLockOffset, appendLockLen)
		if err != nil {
			return err
		}
		if ok {
			return nil
		}
		time.Sleep(time.Millisecond)
	}
	return fmt.Errorf("APPEND: could not acquire append-intent lock (peer holding too long)")
}

func (a *DBFArea) unlockAppendIntent() error {
	if a.dataFile == nil {
		return nil
	}
	return unlockRange(int(a.dataFile.Fd()), appendLockOffset, appendLockLen)
}

// tryLock acquires an exclusive byte-range lock. Non-blocking: returns
// (false, nil) if another process already holds a conflicting lock,
// (false, err) on system error, (true, nil) on success.
func tryLock(fd int, start, length int64) (bool, error) {
	flk := &syscall.Flock_t{
		Type:   syscall.F_WRLCK,
		Whence: int16(0), // SEEK_SET
		Start:  start,
		Len:    length,
	}
	err := syscall.FcntlFlock(uintptr(fd), syscall.F_SETLK, flk)
	if err == nil {
		return true, nil
	}
	if err == syscall.EAGAIN || err == syscall.EACCES {
		// Another process holds a conflicting lock.
		return false, nil
	}
	return false, err
}

// unlockRange releases a byte-range lock previously acquired with tryLock.
func unlockRange(fd int, start, length int64) error {
	flk := &syscall.Flock_t{
		Type:   syscall.F_UNLCK,
		Whence: int16(0),
		Start:  start,
		Len:    length,
	}
	return syscall.FcntlFlock(uintptr(fd), syscall.F_SETLK, flk)
}

// LockFile tries to acquire an exclusive FLOCK on the DBF file.
// Non-blocking. Returns false if another process already holds any lock
// on the header region. Harbour: hb_dbfLock(a, DBOI_LOCKMODE_FILE).
func (a *DBFArea) LockFile() (bool, error) {
	if a.dataFile == nil {
		return false, fmt.Errorf("file not open")
	}
	if a.fileLocked {
		return true, nil // already held
	}
	ok, err := tryLock(int(a.dataFile.Fd()), flockOffset, flockLen(a))
	if err != nil {
		return false, err
	}
	if ok {
		a.fileLocked = true
	}
	return ok, nil
}

// UnlockFile releases the FLOCK held by this workarea.
func (a *DBFArea) UnlockFile() error {
	if a.dataFile == nil || !a.fileLocked {
		return nil
	}
	if err := unlockRange(int(a.dataFile.Fd()), flockOffset, flockLen(a)); err != nil {
		return err
	}
	a.fileLocked = false
	return nil
}

// LockRecord tries to acquire an exclusive lock on a single record.
// recNo == 0 means "current record". Non-blocking.
// Harbour: hb_dbfLock(a, DBOI_LOCKMODE_RECORD).
func (a *DBFArea) LockRecord(recNo uint32) (bool, error) {
	if a.dataFile == nil {
		return false, fmt.Errorf("file not open")
	}
	if recNo == 0 {
		recNo = a.recNo
	}
	if recNo == 0 {
		return false, nil
	}
	if a.lockedRecs != nil && a.lockedRecs[recNo] {
		return true, nil // already held
	}
	start := a.header.RecordOffset(recNo)
	length := int64(a.header.RecordLen)
	ok, err := tryLock(int(a.dataFile.Fd()), start, length)
	if err != nil {
		return false, err
	}
	if ok {
		if a.lockedRecs == nil {
			a.lockedRecs = make(map[uint32]bool, 16)
		}
		a.lockedRecs[recNo] = true
	}
	return ok, nil
}

// UnlockRecord releases a single record lock. recNo == 0 unlocks ALL held
// record locks (Harbour behavior for DBRUNLOCK() with no args).
func (a *DBFArea) UnlockRecord(recNo uint32) error {
	if a.dataFile == nil {
		return nil
	}
	if recNo == 0 {
		// Release all record locks
		if a.lockedRecs == nil {
			return nil
		}
		length := int64(a.header.RecordLen)
		for r := range a.lockedRecs {
			start := a.header.RecordOffset(r)
			_ = unlockRange(int(a.dataFile.Fd()), start, length)
		}
		a.lockedRecs = nil
		return nil
	}
	if a.lockedRecs == nil || !a.lockedRecs[recNo] {
		return nil // not held
	}
	start := a.header.RecordOffset(recNo)
	length := int64(a.header.RecordLen)
	if err := unlockRange(int(a.dataFile.Fd()), start, length); err != nil {
		return err
	}
	delete(a.lockedRecs, recNo)
	return nil
}

// releaseAllLocks is called on Close to release any held locks.
func (a *DBFArea) releaseAllLocks() {
	_ = a.UnlockFile()
	_ = a.UnlockRecord(0)
}