SHMEM_CLEAR_LOCK(3)

📦

version 5.0.10 · 4 versions

💖 SHMEM_CLEAR_LOCK(3) 💖

okay so bestie, we're in the Open MPI section of the manual today and it's giving concurrency control ✨. This page is the whole trio — shmem_set_lock(3), shmem_clear_lock(3), and shmem_test_lock(3) — and they release, lock, and test a mutual exclusion memory lock. no cap, that's literally the job. 🎀

🌸 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)

✨ DESCRIPTION ✨

okay so first up, shmem_set_lock — it sets a mutual exclusion lock, but only after it waits for the lock to be freed by any other PE that's currently holding it. and the way waiting PEs are handled?? first-come, first-served, periodt. nobody's cutting the line, the queue is sacred. 👑

then shmem_clear_lock — this one releases a lock that was previously set by shmem_set_lock, and it does that only after ensuring that all local and remote stores initiated in the critical region are complete. like, it checks that everybody's work actually landed before it hands the key to the next girlie. 🫶

and finally shmem_test_lock — this function sets a mutual exclusion lock only if it is currently cleared. the whole point is that 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 standing around in the club line, you just peek and go. 💅

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

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

📝 NOTES 📝

the term symmetric data object is defined over on intro_shmem(3). go read her, she explains everything. 🦋

🌈 RETURN VALUES 🌈

shmem_test_lock returns 0 if the lock was originally cleared and this call was able to set the lock. it returns 1 if the lock had been set and the call returned without waiting to set the lock. two numbers, two vibes, that's it. 💀