Dependency-injection seam for mutual exclusion around the public API. More...

#include <ra8_fs_seams.h>

Data Fields
void(*	acquire )(void *ctx)
	Take the lock; must block until it is held.
void(*	release )(void *ctx)
	Release the lock taken by the matching acquire call.
void *	ctx
	Caller-owned cookie handed back to both callbacks.

Detailed Description

Dependency-injection seam for mutual exclusion around the public API.

Two function pointers and a cookie. ra8_fs never creates, destroys or names a lock primitive: the caller owns one and hands over the two operations that drive it, exactly as ra8_fs_backend_t hands over the two operations that drive a block device. A ThreadX consumer binds tx_mutex_get / tx_mutex_put over a TX_MUTEX*; a bare-metal-with-interrupts consumer binds a PRIMASK save / restore pair. Neither adapter belongs in this library and neither is present in it.

Both callbacks are invoked with ctx as their only argument, and neither may fail: a lock whose acquire can return an error is not a lock this seam can express, and swallowing that error would be worse than not offering the seam. Wrap such a primitive in an adapter that blocks until it succeeds.

The pair must be re-entrant-free: acquire is never called twice without an intervening release, so a plain non-recursive mutex is the right shape.

Invariant: acquire and release are both non-NULL, or the whole struct is never installed (ra8_fs_set_lock rejects a half-filled one).; ctx may be NULL; it is passed through untouched.

Example:: static void tx_acquire(void* ctx) { (void)tx_mutex_get((TX_MUTEX*)ctx, TX_WAIT_FOREVER); }

static void tx_release(void* ctx) { (void)tx_mutex_put((TX_MUTEX*)ctx); }

static TX_MUTEX s_fs_mutex;

const ra8_fs_lock_t lock = {.acquire = tx_acquire, .release = tx_release, .ctx = &s_fs_mutex};

(void)ra8_fs_set_lock(&lock);

s_fs_mutex
static TX_MUTEX s_fs_mutex
ThreadX mutex the ra8_fs lock seam is bound to (#608).
Definition main.c:85

ra8_fs_set_lock
ra8_err_t ra8_fs_set_lock(const ra8_fs_lock_t *lock)
Install (or remove) the lock taken around every public ra8_fs call.
Definition ra8_fs_fat_lock.c:92

tx_mutex_put
#define tx_mutex_put
Definition ra8_wdt_sup_tx_shim_internal.h:43

TX_WAIT_FOREVER
#define TX_WAIT_FOREVER
Definition ra8_wdt_sup_tx_shim_internal.h:87

tx_mutex_get
#define tx_mutex_get
Definition ra8_wdt_sup_tx_shim_internal.h:41

TX_MUTEX
Opaque mutex stand-in for the host build.
Definition ra8_wdt_sup_tx_shim_internal.h:115

ra8_fs_lock_t::ctx
void * ctx
Caller-owned cookie handed back to both callbacks.
Definition ra8_fs_seams.h:103

See also: ra8_fs_set_lock() Installs (or removes) the binding.

Since: 0.1.0

Definition at line 89 of file ra8_fs_seams.h.

Field Documentation

◆ acquire

void(* ra8_fs_lock_t::acquire) (void *ctx)

Take the lock; must block until it is held.

Parameters

[in] ctx The ctx cookie, passed through unmodified.

Definition at line 94 of file ra8_fs_seams.h.

Referenced by ra8_fs_set_lock().

◆ ctx

void* ra8_fs_lock_t::ctx

Caller-owned cookie handed back to both callbacks.

Definition at line 103 of file ra8_fs_seams.h.

◆ release

void(* ra8_fs_lock_t::release) (void *ctx)

Release the lock taken by the matching acquire call.