SETTMASK(3PVM)

📦 version 3.4.6, in debian bookworm, ubuntu jammy

✨ SETTMASK 💅

okay bestie, this is the PVM Version 3.4 page for the trace-mask girlies — SETTMASK(3PVM), no cap. it's giving "i want to know exactly what every libpvm function is doing" and honestly? iconic.

NAME 🎀

pvm_gettmask, pvm_settmask — get or set the trace mask of a task or its children. yes queen, you can peek at your own mask, and you can also decide what mask your future children get. main character energy fr fr.

SYNOPSIS ✨

C 🌸

#include <pvm3.h>
#include <pvmtev.h>

int info = pvm_gettmask( int who, Pvmtmask mask )
int info = pvm_settmask( int who, Pvmtmask mask )

Fortran — Not Available 💀 sorry fortran bestie, this one's not for you.

PARAMETERS 🫶

who — tells it which trace mask you're getting or setting, and it's one of these two:
- PvmTaskSelf — the current task. that's you. hi. 💖
- PvmTaskChild — children tasks to be spawned. the little ones. 👑
mask — the trace mask, and she's owned by the caller. on a pvm_gettmask call she gets filled in with the current trace vector; on a pvm_settmask call she's the thing you're using to set the current trace vector. either way she's yours to hold. 🎀
info — the status code that comes back. anything less than zero means error, and we hate that for you. 😭

DESCRIPTION 🦋

okay so. every single task has a trace mask, and that mask lets you individually enable tracing for each and every libpvm function. picky? yes. powerful? also yes. ✨

the mask is inherited from its parent task — or, if the task has no parent at all, it starts out initially all cleared (a fresh little baby mask, no bits set, adorable). whenever calls get made to functions in libpvm, the parameters and the results get sent in messages to the task's trace sink — that's the variable PvmTraceTid, which you set by calling pvm_setopt (see man page, iykyk).

the PVM console and XPVM use this whole system to get trace data out of application programs. so like, this is the plumbing that makes the pretty pictures happen. 🎀

a task can get or set either its own trace mask, or the mask that gets passed to children it spawns. but listen — the mask must be set before the spawn call. setting the child trace mask does absolutely nothing to children that are already running. they're grown, they've moved on, you can't retroactively parent them. 🙈

the trace mask can be kept in a temporary variable, declared like:

Pvmtmask mymask;

right now, this is a character array with approximately 80 bits. cute, compact, slays.

the four macros 🧚

there are four macros defined to manipulate trace masks. along with the functions, these let a program get the current trace mask, modify it or save it, and put it back. the full squad:

TEV_INIT_MASK(mask)
TEV_SET_MASK(mask, kind)
TEV_UNSET_MASK(mask, kind)
TEV_CHECK_MASK(mask, kind)

TEV_INIT_MASK — initializes a mask to all bits cleared, and you must use it to initialize a trace mask... unless that's already been done by setting it from pvm_gettmask. either way, don't skip this step bestie, an uninitialized mask is a bad vibe. 💀
TEV_SET_MASK — sets a bit in a mask. the bit values are defined in <pvmtev.h>.
TEV_UNSET_MASK — clears a single bit. bye bit. 💅
TEV_CHECK_MASK — checks to see if a bit is set, returning nonzero if true.

Note: most events in the trace mask come in pairs. the first one (ending in ...0) is generated on entry to a function, and the second (...1) on exit. the trace mask has only half as many bits as there are events, because events are enabled in pairs. in other words, if you select TEV_SEND0, you'll also get TEV_SEND1. they're a package deal. soulmates, honestly. 🫶

why is it a string tho 🌈

the trace mask is deliberately kept as a printable (and null-terminated) string, and there are two reasons:

it gets passed through the environment between tasks, in the form:

PVMTMASK=@@AAOG@@NO@L@@@@@@@@

so the pvmd doesn't have to explicitly manage it. it just vibes in the env and everyone reads it. 🦋

the mask variables can be passed between tasks using pvm_pkstr() or otherwise manipulated as strings. flexible. iconic. periodt.

pvm_gettmask and pvm_settmask return PvmOk on success, else a negative value.

EXAMPLES 🍓

C: 💖

#include <pvm3.h>
#include <pvmtev.h>

Pvmtmask m;

pvm_gettmask( PvmTaskChild, m );
TEV_SET_MASK(m, TEV_ADDHOSTS0 );
pvm_settmask( PvmTaskChild, m );
pvm_spawn( "worker", (char **)0, PvmTaskDefault, "", 1, (int *)0);

see how she grabbed the child mask, flipped on one little bit, put it back, and then spawned? that's the order. mask first, spawn second. don't do it backwards, i'm begging. 😭

ERRORS 💀

the following error condition can be returned by pvm_gettmask or pvm_settmask:

PvmBadParam — invalid value for who argument. bestie you gave it a who it doesn't recognize. it's not mad, it's just disappointed. 🙈