SHMEM_TEST_LOCK(3)

💅 SHMEM_TEST_LOCK(3) — an Open MPI moment 💅

ok so bestie, this is section 3 of the Open MPI manual, and today we're learning about the lock girlies: shmem_set_lock(3), shmem_clear_lock(3) and shmem_test_lock(3). yes they all share one page, they're a package deal 🎀

---

✨ NAME ✨

shmem_set_lock(3), shmem_clear_lock(3), shmem_test_lock(3) — releases, locks, and tests a mutual exclusion memory lock. that's the whole vibe. three functions, one job: keeping your critical region from getting jumped by everybody at once 💅

---

🌸 SYNOPSIS 🌸

C or C++:

#include <mpp/shmem.h>

void shmem_clear_lock(volatile long *lock)

void shmem_set_lock(volatile long *lock)

int shmem_test_lock(volatile long *lock)

Fortran:

INCLUDE "mpp/shmem.fh"

INTEGER lock, SHMEM_TEST_LOCK

CALL SHMEM_CLEAR_LOCK(lock)

CALL SHMEM_SET_LOCK(lock)

I = SHMEM_TEST_LOCK(lock)

like, copy-paste these exactly, bestie, don't freestyle the signatures 🙈

---

🦋 DESCRIPTION 🦋

okay so, storytime. shmem_set_lock sets a mutual exclusion lock — and the way it does it is it waits for the lock to be freed by any other PE that's currently holding it. and here's the slay part: waiting PEs are assured of getting the lock in a first-come, first-served manner. no line-cutting. the queue is sacred. 🧚

shmem_clear_lock releases a lock that was previously set by shmem_set_lock — but only after making sure that all the local and remote stores you started inside the critical region are actually complete. she's thorough. she does not leave the group chat mid-sentence. ✨

shmem_test_lock sets a mutual exclusion lock only if it's currently cleared. this one's for my no-ghosting girlies: by using this function, a PE can avoid blocking on a set lock. if the lock is currently set, the function just returns without waiting. no sitting around, no "seen 2:14am", she moves on. 💀

these routines are appropriate for protecting a critical region from simultaneous update by multiple PEs. they accept the following argument:

• lock — a symmetric data object that is a scalar variable or an array of length 1. it must be set to 0 on all processing elements (PEs) prior to the first use. lock must be of type integer. if you're in Fortran-land, it must be of default kind. (yes, all of them. no cap. 🔥)

---

📝 NOTES 📝

the term symmetric data object is defined on intro_shmem(3) — go check her out if you're nosy like me 🫶

---

⭐ RETURN VALUES ⭐

shmem_test_lock is the one that actually gives you a number back:

• returns 0 if the lock was originally cleared and this call was able to set the lock — you got her 👑
• returns 1 if the lock had been set and the call returned without waiting to set the lock — she was taken, no waiting around 😭

👀 SEE ALSO 👀

intro_shmem(3)

---

💖 COPYRIGHT 💖

2003-2026, The Open MPI Community

---

okay and that's the page!! written down for you on May 14, 2026, from the Open MPI girlies, SHMEM_TEST_LOCK(3) era. go forth and lock responsibly bestie 🍓💜