PetscSFRegisterPersistent#
Register root and leaf data as memory regions that will be used for repeated PetscSF communications.
Synopsis#
#include "petscsf.h" 
PetscErrorCode PetscSFRegisterPersistent(PetscSF sf, MPI_Datatype unit, const void *rootdata, const void *leafdata)
Collective
Input Parameters#
- sf - star forest 
- unit - the data type contained within the root and leaf data 
- rootdata - root data that will be used for multiple PetscSF communications 
- leafdata - leaf data that will be used for multiple PetscSF communications 
Notes#
Implementations of PetscSF can make optimizations
for repeated communication using the same memory regions, but these optimizations
can be unsound if rootdata or leafdata is deallocated and the PetscSF is not informed.
The intended pattern is
  PetscMalloc2(nroots, &rootdata, nleaves, &leafdata);
  PetscSFRegisterPersistent(sf, unit, rootdata, leafdata);
  // repeated use of rootdata and leafdata will now be optimized
  PetscSFBcastBegin(sf, unit, rootdata, leafdata, MPI_REPLACE);
  PetscSFBcastEnd(sf, unit, rootdata, leafdata, MPI_REPLACE);
  // ...
  PetscSFReduceBegin(sf, unit, leafdata, rootdata, MPI_SUM);
  PetscSFReduceEnd(sf, unit, leafdata, rootdata, MPI_SUM);
  // ... (other communications)
  // rootdata and leafdata must be deregistered before freeing
  // skipping this can lead to undefined behavior including
  // deadlocks
  PetscSFDeregisterPersistent(sf, unit, rootdata, leafdata);
  // it is now safe to free rootdata and leafdata
  PetscFree2(rootdata, leafdata);
If you do not register rootdata and leafdata it will not cause an error,
but optimizations that reduce the setup time for each communication cannot be
made.  Currently, the only implementation of PetscSF that benefits from
PetscSFRegisterPersistent() is PETSCSFWINDOW.  For the default
PETSCSFBASIC there is no benefit to using PetscSFRegisterPersistent().
See Also#
PetscSF, PETSCSFWINDOW, PetscSFDeregisterPersistent()
Level#
advanced
Location#
Examples#
Implementations#
PetscSFRegisterPersistent_Window() in src/vec/is/sf/impls/window/sfwindow.c
Index of all PetscSF routines
Table of Contents for all manual pages
Index of all manual pages