David
/
Foundry
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Foundry/tt/ft_tt_udrv_claim.c

430 lines
13 KiB
C
Raw Blame History

/* SPDX-License-Identifier: AGPL-3.0-or-later */
/* Copyright (C) 2026 David (Corey) Herrera */
/**
* @file ft_tt_udrv_claim.c
* @brief Implementation of flock-based multi-tenant resource claims (see
* ft_tt_udrv_claim.h for the design and the rejected alternatives).
*
* @status Off-hardware complete; this module never touches the card.
* @issues None
* @todo None
*/
/* flock(2) is BSD, not POSIX, so a bare _POSIX_C_SOURCE hides it on both
* platforms this code is built on. Same shape as the _DEFAULT_SOURCE note in
* DEV_NOTES §5 for MADV_DONTNEED: macOS declares BSD interfaces under
* _DARWIN_C_SOURCE, glibc under _DEFAULT_SOURCE (which implies POSIX 2008). */
#if defined(__APPLE__)
#define _DARWIN_C_SOURCE
#else
#define _DEFAULT_SOURCE
#endif
#include "ft_tt_udrv_claim.h"
#include <errno.h>
#include <fcntl.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/file.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <time.h>
#include <unistd.h>
#include "ft_tt_udrv.h"
/** Single-host coordination: a pid means nothing on another machine, and /tmp
* being cleared at reboot is desirable because a reboot invalidates every pid
* a record could name. Same reasoning as tools/ft_tt_card_lock.c. */
#define FT_TT_UDRV_CLAIM_DEFAULT_ROOT "/tmp/ft_tt_udrv.d"
/** Room for "<root>/<card>/<name>/<index>.claim" with margin, sized so the
* compiler can prove -Wformat-truncation is unreachable rather than sized to
* the tightest bound that compiles today. */
#define CLAIM_PATH_MAX 512u
struct ft_tt_udrv_claim {
ft_tt_udrv_claim_namespace ns;
uint32_t index;
int fd; /**< holds the flock; closing it releases the claim */
};
/** True when `text` is a usable single path component. */
static bool is_path_component(const char *text, size_t capacity)
{
size_t length;
if (!text)
return false;
length = strlen(text);
if (length == 0u || length >= capacity)
return false;
if (strchr(text, '/') != NULL)
return false;
/* "." and ".." would escape or alias the namespace directory. */
if (strcmp(text, ".") == 0 || strcmp(text, "..") == 0)
return false;
return true;
}
/** Bounded copy that always terminates and cannot trip -Wformat-truncation. */
static void copy_bounded(char *dest, size_t dest_bytes, const char *src)
{
size_t length;
if (dest_bytes == 0u)
return;
length = strlen(src);
if (length >= dest_bytes)
length = dest_bytes - 1u;
memcpy(dest, src, length);
dest[length] = '\0';
}
/**
* mkdir the path, treating "already exists" as success, and make sure the mode
* really IS 0777 rather than whatever the umask allowed.
*
* THE UMASK IS THE TRAP, AND IT IS NOT HYPOTHETICAL. `mkdir(0777)` under root's
* usual umask 022 produces a **0755 root-owned** directory, and every later
* non-root job then fails to claim with `rc=-4` — which reads like a hardware
* fault, and has cost this project time. Whoever creates the tree first decides
* everyone else's access, and on this box that is usually a `sudo` bring-up.
*
* The chmod is deliberately NOT conditional on having just created the directory:
* a tree left too narrow by an EARLIER root run is exactly the case that needs
* fixing, and a chmod attempted by a non-owner simply fails and is ignored. These
* are /tmp lock files and not secrets — the claim IS the lock, so a user who
* cannot open the file cannot take part in the arbitration at all.
*/
static int ensure_directory(const char *path)
{
if (mkdir(path, 0777) != 0 && errno != EEXIST)
return FT_TT_UDRV_EIO;
(void)chmod(path, 0777);
return FT_TT_UDRV_OK;
}
/** Widen a claim file to 0666 whatever the umask did to it, for the same reason
* ensure_directory() widens the tree. Ignored when we do not own it. */
static void widen_claim_file(int fd)
{
(void)fchmod(fd, 0666);
}
/** Build "<root>/<card>/<name>" and create every level of it. */
static int ensure_namespace_directory(const ft_tt_udrv_claim_namespace *ns, char *out_path,
size_t out_bytes)
{
char level[CLAIM_PATH_MAX];
int written;
written = snprintf(level, sizeof(level), "%s", ns->root);
if (written < 0 || (size_t)written >= sizeof(level))
return FT_TT_UDRV_EINVAL;
if (ensure_directory(level) != FT_TT_UDRV_OK)
return FT_TT_UDRV_EIO;
written = snprintf(level, sizeof(level), "%s/%s", ns->root, ns->card);
if (written < 0 || (size_t)written >= sizeof(level))
return FT_TT_UDRV_EINVAL;
if (ensure_directory(level) != FT_TT_UDRV_OK)
return FT_TT_UDRV_EIO;
written = snprintf(level, sizeof(level), "%s/%s/%s", ns->root, ns->card, ns->name);
if (written < 0 || (size_t)written >= sizeof(level))
return FT_TT_UDRV_EINVAL;
if (ensure_directory(level) != FT_TT_UDRV_OK)
return FT_TT_UDRV_EIO;
copy_bounded(out_path, out_bytes, level);
return FT_TT_UDRV_OK;
}
/** Path of one index's lock file, and of its record. */
static int claim_paths(const ft_tt_udrv_claim_namespace *ns, uint32_t index, char *out_lock,
size_t lock_bytes, char *out_record, size_t record_bytes)
{
char directory[CLAIM_PATH_MAX];
int written;
int rc;
rc = ensure_namespace_directory(ns, directory, sizeof(directory));
if (rc != FT_TT_UDRV_OK)
return rc;
written = snprintf(out_lock, lock_bytes, "%s/%u.lock", directory, index);
if (written < 0 || (size_t)written >= lock_bytes)
return FT_TT_UDRV_EINVAL;
written = snprintf(out_record, record_bytes, "%s/%u.claim", directory, index);
if (written < 0 || (size_t)written >= record_bytes)
return FT_TT_UDRV_EINVAL;
return FT_TT_UDRV_OK;
}
/**
* Write the advisory record naming this holder.
*
* Deliberately AFTER the flock and deliberately not load-bearing: the lock is
* the claim. A failure here is reported but does not fail the acquisition,
* because refusing a resource we already own would be a worse outcome than an
* unnamed holder.
*/
static void write_record(const char *record_path, const char *reason)
{
FILE *file = fopen(record_path, "w");
if (!file)
return;
(void)fprintf(file, "pid %ld\nreason %s\nacquired %lld\n", (long)getpid(),
reason ? reason : "", (long long)time(NULL));
(void)fchmod(fileno(file), 0666);
(void)fclose(file);
}
/** Read pid and reason out of a record. Missing or malformed reads as pid 0. */
static void read_record(const char *record_path, pid_t *out_pid, char *out_reason,
size_t reason_bytes)
{
char line[CLAIM_PATH_MAX];
FILE *file;
*out_pid = 0;
if (reason_bytes > 0u)
out_reason[0] = '\0';
file = fopen(record_path, "r");
if (!file)
return;
while (fgets(line, (int)sizeof(line), file) != NULL) {
size_t length = strlen(line);
while (length > 0u && (line[length - 1u] == '\n' || line[length - 1u] == '\r'))
line[--length] = '\0';
if (strncmp(line, "pid ", 4) == 0) {
*out_pid = (pid_t)strtol(line + 4, NULL, 10);
} else if (strncmp(line, "reason ", 7) == 0) {
copy_bounded(out_reason, reason_bytes, line + 7);
}
}
(void)fclose(file);
}
int ft_tt_udrv_claim_namespace_init(ft_tt_udrv_claim_namespace *out_namespace, const char *root,
const char *card, const char *name, uint32_t count)
{
if (!out_namespace || count == 0u)
return FT_TT_UDRV_EINVAL;
if (!is_path_component(card, FT_TT_UDRV_CLAIM_NAMESPACE_MAX))
return FT_TT_UDRV_EINVAL;
if (!is_path_component(name, FT_TT_UDRV_CLAIM_NAMESPACE_MAX))
return FT_TT_UDRV_EINVAL;
memset(out_namespace, 0, sizeof(*out_namespace));
copy_bounded(out_namespace->root, sizeof(out_namespace->root),
root ? root : FT_TT_UDRV_CLAIM_DEFAULT_ROOT);
copy_bounded(out_namespace->card, sizeof(out_namespace->card), card);
copy_bounded(out_namespace->name, sizeof(out_namespace->name), name);
out_namespace->count = count;
if (out_namespace->root[0] == '\0')
return FT_TT_UDRV_EINVAL;
return FT_TT_UDRV_OK;
}
int ft_tt_udrv_claim_acquire(const ft_tt_udrv_claim_namespace *ns, uint32_t index,
const char *reason, ft_tt_udrv_claim **out_claim)
{
char lock_path[CLAIM_PATH_MAX];
char record_path[CLAIM_PATH_MAX];
ft_tt_udrv_claim *claim = NULL;
int fd = -1;
int rc;
if (!ns || !out_claim || index >= ns->count)
return FT_TT_UDRV_EINVAL;
if (reason && strlen(reason) >= FT_TT_UDRV_CLAIM_REASON_MAX)
return FT_TT_UDRV_EINVAL;
rc = claim_paths(ns, index, lock_path, sizeof(lock_path), record_path, sizeof(record_path));
if (rc != FT_TT_UDRV_OK)
return rc;
/* O_CLOEXEC: a claim that survived exec() would be held by a process that
* does not know it holds it, and released at a moment nobody chose. */
fd = open(lock_path, O_RDWR | O_CREAT | O_CLOEXEC, 0666);
if (fd < 0)
return FT_TT_UDRV_EIO;
widen_claim_file(fd);
if (flock(fd, LOCK_EX | LOCK_NB) != 0) {
rc = (errno == EWOULDBLOCK || errno == EINTR) ? FT_TT_UDRV_EAGAIN : FT_TT_UDRV_EIO;
(void)close(fd);
return rc;
}
claim = calloc(1u, sizeof(*claim));
if (!claim) {
(void)close(fd); /* releases the flock */
return FT_TT_UDRV_ENOMEM;
}
claim->ns = *ns;
claim->index = index;
claim->fd = fd;
write_record(record_path, reason);
*out_claim = claim;
return FT_TT_UDRV_OK;
}
int ft_tt_udrv_claim_acquire_any(const ft_tt_udrv_claim_namespace *ns, const uint32_t *reserved,
size_t reserved_count, const char *reason,
ft_tt_udrv_claim **out_claim)
{
uint32_t index;
if (!ns || !out_claim)
return FT_TT_UDRV_EINVAL;
if (reserved_count > 0u && !reserved)
return FT_TT_UDRV_EINVAL;
for (index = 0u; index < ns->count; index++) {
bool is_reserved = false;
size_t i;
int rc;
for (i = 0u; i < reserved_count; i++) {
if (reserved[i] == index) {
is_reserved = true;
break;
}
}
if (is_reserved)
continue;
rc = ft_tt_udrv_claim_acquire(ns, index, reason, out_claim);
if (rc == FT_TT_UDRV_OK)
return FT_TT_UDRV_OK;
/* EAGAIN means somebody else holds it; anything else is a real error
* and must not be hidden by trying the next index. */
if (rc != FT_TT_UDRV_EAGAIN)
return rc;
}
return FT_TT_UDRV_EAGAIN;
}
uint32_t ft_tt_udrv_claim_index(const ft_tt_udrv_claim *claim)
{
return claim ? claim->index : UINT32_MAX;
}
int ft_tt_udrv_claim_release(ft_tt_udrv_claim *claim)
{
char lock_path[CLAIM_PATH_MAX];
char record_path[CLAIM_PATH_MAX];
int rc = FT_TT_UDRV_OK;
if (!claim)
return FT_TT_UDRV_OK;
if (claim_paths(&claim->ns, claim->index, lock_path, sizeof(lock_path), record_path,
sizeof(record_path)) == FT_TT_UDRV_OK) {
if (unlink(record_path) != 0 && errno != ENOENT)
rc = FT_TT_UDRV_EIO;
}
/* Closing is what releases the lock; do it last so the record is gone
* before the resource can be re-claimed by anyone else. */
if (close(claim->fd) != 0)
rc = FT_TT_UDRV_EIO;
free(claim);
return rc;
}
int ft_tt_udrv_claim_scan(const ft_tt_udrv_claim_namespace *ns, ft_tt_udrv_claim_info *out_info,
size_t info_cap, uint32_t *out_held)
{
uint32_t index;
uint32_t held = 0u;
if (!ns || !out_info || info_cap < (size_t)ns->count)
return FT_TT_UDRV_EINVAL;
for (index = 0u; index < ns->count; index++) {
char lock_path[CLAIM_PATH_MAX];
char record_path[CLAIM_PATH_MAX];
ft_tt_udrv_claim_info *info = &out_info[index];
int fd;
int rc;
memset(info, 0, sizeof(*info));
info->index = index;
rc = claim_paths(ns, index, lock_path, sizeof(lock_path), record_path,
sizeof(record_path));
if (rc != FT_TT_UDRV_OK)
return rc;
read_record(record_path, &info->pid, info->reason, sizeof(info->reason));
info->pid_alive = (info->pid > 0) && (kill(info->pid, 0) == 0 || errno == EPERM);
fd = open(lock_path, O_RDWR | O_CREAT | O_CLOEXEC, 0666);
if (fd < 0)
return FT_TT_UDRV_EIO;
widen_claim_file(fd);
/* The lock is the truth. A record can lie in both directions: orphaned
* after a crash, or absent because the holder died before writing it. */
if (flock(fd, LOCK_EX | LOCK_NB) == 0) {
info->held = false;
(void)flock(fd, LOCK_UN);
} else {
info->held = true;
held++;
}
(void)close(fd);
/* Sweep the orphan: the lock is free and the record names a pid that
* is gone, so the record is stale and would otherwise mislead the next
* person to read a report. */
if (!info->held && info->pid > 0 && !info->pid_alive) {
(void)unlink(record_path);
info->pid = 0;
info->reason[0] = '\0';
}
}
if (out_held)
*out_held = held;
return FT_TT_UDRV_OK;
}
Reference in New Issue View Git Blame Copy Permalink