amiga-bootcamp/06_exec_os/semaphores.md

← Home · Exec Kernel

Semaphores — SignalSemaphore, ObtainSemaphore, Shared/Exclusive

Overview

Semaphores are the AmigaOS mechanism for mutual exclusion and shared-read access to resources. Unlike Forbid() (which blocks all scheduling), semaphores allow other tasks to run while waiting — the waiting task simply sleeps until the resource is available.

---

struct SignalSemaphore

/* exec/semaphores.h — NDK39 */
struct SignalSemaphore {
    struct Node  ss_Link;       /* ln_Type = NT_SIGNALSEM */
                                /* ln_Name = semaphore name (public) */
    WORD         ss_NestCount;  /* how many times THIS task has obtained it */
    struct MinList ss_WaitQueue;/* tasks waiting for exclusive access */
    struct SemaphoreRequest ss_MultipleLink; /* shared-reader slot */
    struct Task *ss_Owner;      /* task holding exclusive lock (or NULL) */
    WORD         ss_QueueCount; /* number of waiters */
};

---

Initialising a Semaphore

/* Stack or AllocMem — always initialise before use: */
struct SignalSemaphore sem;
InitSemaphore(&sem);   /* LVO -558 */

/* Public (named) semaphore — so other tasks can find it: */
sem.ss_Link.ln_Name = "myapp.lock";
AddSemaphore(&sem);    /* LVO -564 */

/* Later: */
RemSemaphore(&sem);    /* LVO -570 */

---

Exclusive (Write) Lock

/* Block until this task holds the semaphore exclusively: */
ObtainSemaphore(&sem);    /* LVO -534 */

/* --- critical section: only one task in here at a time --- */

ReleaseSemaphore(&sem);   /* LVO -546 */

Non-Blocking Try

/* Returns TRUE if obtained, FALSE if someone else holds it: */
if (AttemptSemaphore(&sem)) {   /* LVO -540 */
    /* got it */
    ReleaseSemaphore(&sem);
} else {
    /* resource busy — do something else */
}

---

Shared (Read) Lock

Multiple tasks may hold a shared lock simultaneously. An exclusive lock blocks until all shared holders release.

ObtainSemaphoreShared(&sem);   /* LVO -768 */

/* --- read-only access: multiple tasks may be here at once --- */

ReleaseSemaphore(&sem);        /* same release for both modes */

---

Nesting

Semaphores are reentrant — the same task can call ObtainSemaphore multiple times. The ss_NestCount tracks how many times the current owner has obtained it. ReleaseSemaphore must be called the same number of times.

ObtainSemaphore(&sem);   /* NestCount = 1 */
ObtainSemaphore(&sem);   /* NestCount = 2 — safe, same task */
ReleaseSemaphore(&sem);  /* NestCount = 1 */
ReleaseSemaphore(&sem);  /* NestCount = 0 — fully released, waiters wake */

---

Semaphore vs Forbid/Disable

Mechanism	Blocks	Other tasks run while waiting?	Interrupt safe?
Forbid()	All task switching	❌ No	✅ (interrupts still run)
Disable()	All task switching + interrupts	❌ No	✅
ObtainSemaphore()	Only contending tasks	✅ Yes	❌ Not from interrupt context

Use semaphores for anything that may take more than a few microseconds. Use Forbid() only for very short list manipulations.

---

References

• NDK39: exec/semaphores.h
• ADCD 2.1: InitSemaphore, ObtainSemaphore, ObtainSemaphoreShared, ReleaseSemaphore, AttemptSemaphore
• Amiga ROM Kernel Reference Manual: Exec — semaphores chapter