SETTMASK(3PVM)

💅 SETTMASK — the pvm_gettmask / pvm_settmask era

okay so bestie, welcome to PVM Version 3.4, page SETTMASK(3PVM). this is the one about ✨trace masks✨, aka the little permission slips that decide which libpvm functions get to spill their tea to the trace sink. iconic behavior honestly.

---

🌸 NAME 🌸

pvm_gettmask, pvm_settmask — get or set the trace mask of a task or its children, 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 babes, it's just not.

---

🎀 PARAMETERS 🎀

• who — tells the function which trace mask we're getting or setting, and it's giving very specific options:
  • PvmTaskSelf — the current task, me, myself and I 💅
  • PvmTaskChild — children tasks to be spawned, the little ones 👶
• mask — the trace mask, and it's owned by the caller. on pvm_gettmask it gets filled in with the current trace vector; on pvm_settmask it's the thing you're using to set the current trace vector. no cap.
• info — the status code that comes back. anything less than zero means error, and yes we're gonna talk about that later 😭

---

🦋 DESCRIPTION 🦋

so every task has a trace mask, right? and that mask is how you individually enable tracing of each and every libpvm function. it gets inherited from its parent task — or, if the task has no parent, it starts out initially all cleared (a clean slate, main character origin story energy).

when calls get made to functions in libpvm, the parameters and results are sent in messages to the trace sink of the task. that sink lives in the variable PvmTraceTid, which you set by calling pvm_setopt — see that man page, iykyk.

the PVM console and XPVM use this whole system to get trace data from application programs. yeah. they're obsessed with your traces.

a task can get or set either its own trace mask or the mask passed to the children it spawns. ⚠️ but listen: the mask has to be set before the spawn call. setting the child trace mask has no effect on already-running children. it's giving "too late babe, they already left the group chat."

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. tiny but mighty 🧚

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

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 it must be used to initialize a trace mask — unless that's done by setting it from pvm_gettmask, obviously. TEV_SET_MASK sets a bit in a mask. bit values are defined in <pvmtev.h>. likewise, TEV_UNSET_MASK clears a single bit, and TEV_CHECK_MASK checks to see if a bit is set, returning nonzero if true. slay.

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 one (...1) on exit. the trace mask has only half as many bits as there are events; events are enabled in pairs. in other words, if you select TEV_SEND0, you'll also get TEV_SEND1. they're a package deal, no splitting them up.

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

1. it's passed through the environment between tasks, in the form:

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

so the pvmd doesn't have to explicitly manage it. king behavior honestly 👑

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

pvm_gettmask and pvm_settmask return PvmOk on success, else a negative value. that's the whole vibe check.

---

🌈 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);

look at her go. get the child mask, flip on a bit, set it back, then spawn. order matters bestie 🫶

---

💀 ERRORS 💀

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

• PvmBadParam — invalid value for the who argument. you gave it something it doesn't recognize. not me accidentally passing garbage to who 🙈

---

⭐ SEE ALSO ⭐

pvm(1PVM), pvm_getopt(3PVM), pvm_setopt(3PVM)

---

and that's the page!! 💖 brought to you by PVM Version 3.4, dated 16 March, 1994 — yeah she's vintage, she's a classic, she ate and left no crumbs. go forth and trace responsibly ✨🎀🦋