SHMEM_LONG_WAIT(3)

📦
version 5.0.10 · 4 versions
, in ubuntu stonking

💖 SHMEM_LONG_WAIT(3) — aka the wait-until-someone-changes-my-variable page 💖

okay bestie, so this is the shmem_long_wait family page (manual, section 3), and honestly? it's the "text me back" of parallel programming. it's a whole squad of wait routines and i'm gonna introduce you to every single one, no cap:

  • shmem_int_wait, shmem_int_wait_until
  • shmem_int4_wait, shmem_int4_wait_until
  • shmem_int8_wait, shmem_int8_wait_until
  • shmem_long_wait, shmem_long_wait_until
  • shmem_longlong_wait, shmem_longlong_wait_until
  • shmem_short_wait, shmem_short_wait_until
  • shmem_wait, shmem_wait_until

and what do they all do? they wait for a variable on the local processing element (PE) to change. periodt. 💅

✨ SYNOPSIS ✨

C or C++:

#include <mpp/shmem.h>

void shmem_int_wait(volatile int *var, int value)

void shmem_int_wait_until(volatile int *var, int cond, int value)

void shmem_long_wait(volatile long *var, long value)

void shmem_long_wait_until(volatile long *var, int cond, long value)

void shmem_longlong_wait(volatile long long *var, long long value)

void shmem_longlong_wait_until(volatile long long *var, int cond,
  long long value)

void shmem_short_wait(volatile short *var, short value)

void shmem_short_wait_until(volatile short *var, int cond,
  short value)

void shmem_wait(volatile long *ivar, long cmp_value)

void shmem_wait_until(volatile long *ivar, int cmp, long value)

Fortran, my beloved:

INCLUDE "mpp/shmem.fh"

CALL SHMEM_INT4_WAIT(ivar, cmp_value)

CALL SHMEM_INT4_WAIT_UNTIL(ivar, cmp, cmp_value)

CALL SHMEM_INT8_WAIT(ivar, cmp_value)

CALL SHMEM_INT8_WAIT_UNTIL(ivar, cmp, cmp_value)

CALL SHMEM_WAIT(ivar, cmp_value)

CALL SHMEM_WAIT_UNTIL(ivar, cmp, cmp_value)

🦋 DESCRIPTION 🦋

so here's the vibe: shmem_wait and shmem_wait_until are literally just sitting there waiting for ivar to get changed by a remote write or an atomic swap issued by a different processor. it's giving "i'll be here when you're ready." these routines are made for point-to-point directed synchronization (iykyk).

a call to shmem_wait does not return until some other processor writes a value into ivar on the waiting processor that is not equal to cmp_value. not even a little. it stays put. 😤

a call to shmem_wait_until does not return until some other processor changes ivar so it satisfies the condition implied by cmp and cmp_value.

this whole mechanism is lowkey iconic when a processor needs to tell another processor that it finished doing a thing. 💌

the arguments, bestie — all of them

  • target — the remotely accessible integer data object to be updated on the remote PE. if you're on C/C++, the type of target should match what the SYNOPSIS section implies. if you're on the Fortran compiler, it must be of type integer with an element size of 4 bytes for SHMEM_INT4_ADD and 8 bytes for SHMEM_INT8_ADD.
  • value — the value to be atomically added to target. if you're on C/C++, the type of value should match what the SYNOPSIS section implies. if you're on Fortran, it must be of type integer with an element size of target.
  • pe — an integer that indicates the PE number upon which target is to be updated. if you're on Fortran, it must be a default integer value.
  • ivar — a remotely accessible integer variable that is being updated by another PE. if you're on C/C++, the type of ivar should match what the SYNOPSIS section implies. if you're on Fortran, ivar must be a specific sized integer type according to the function being called, like this:
    • shmem_wait, shmem_wait_until: default INTEGER
    • shmem_int4_wait, shmem_int4_wait_until: INTEGER*4
    • shmem_int8_wait, shmem_int8_wait_until: INTEGER*8
  • cmp — the compare operator that compares ivar with cmp_value. cmp must be of type integer. if you're on Fortran, it must be of default kind. if you're on C/C++, the type of cmp should match what the SYNOPSIS section implies. here are the cmp values that are supported, and yes, we're listing all six because i love you:
    • SHMEM_CMP_EQ — Equal
    • SHMEM_CMP_NE — Not equal
    • SHMEM_CMP_GT — Greater than
    • SHMEM_CMP_LE — Less than or equal to
    • SHMEM_CMP_LT — Less than
    • SHMEM_CMP_GE — Greater than or equal to
  • cmp_value — cmp_value must be of type integer. if you're on C/C++, the type of cmp_value should match what the SYNOPSIS section implies. if you're on Fortran, cmp_value must be an integer of the same size and kind as ivar. the shmem_wait routines return when ivar is no longer equal to cmp_value. the shmem_wait_until routines return when the compare condition is true. and that compare condition? it's defined by the ivar argument compared with the cmp_value using the comparison operator, cmp. that's the whole tea. 🍵

🌈 EXAMPLES 🌈

Example 1: the following call returns when variable ivar is not equal to 100:

INTEGER*8 IVAR

CALL SHMEM_INT8_WAIT(IVAR, INT8(100))

Example 2: the following call to SHMEM_INT8_WAIT_UNTIL is equivalent to the call to SHMEM_INT8_WAIT in example 1:

INTEGER*8 IVAR

CALL SHMEM_INT8_WAIT_UNTIL(IVAR, SHMEM_CMP_NE, INT8(100))

Example 3: the following C/C++ call waits until the sign bit in ivar is set by a transfer from a remote PE:

int ivar;

shmem_int_wait_until(&ivar, SHMEM_CMP_LT, 0);

Example 4: the following Fortran example is in the context of a subroutine:

SUBROUTINE EXAMPLE()
  INTEGER FLAG_VAR
  COMMON/FLAG/FLAG_VAR
  . . .
  FLAG_VAR = FLAG_VALUE ! initialize the event variable
  . . .
  IF (FLAG_VAR .EQ. FLAG_VALUE) THEN
    CALL SHMEM_WAIT(FLAG_VAR, FLAG_VALUE)
  ENDIF
  FLAG_VAR = FLAG_VALUE ! reset the event variable for next time
  . . .
END

👀 SEE ALSO 👀

go read these next, bestie:

Copyright 2003-2026, The Open MPI Community. yeah, they've been at this a minute. respect. 👑

and that's the whole page, babe 🫶 this edition of the SHMEM_LONG_WAIT(3) manual shipped with Open MPI, dated Sep 10, 2026. go forth, wait on your variables, and slay 💖✨🎀

📦 where this page comes from