Petsc's xxxSetxxx methods: Own Pointer or Copy Values?

Question

In PETSC, there are many xxxSetyyy methods, e.g. MatSetLocalToGlobalMapping(A,rmap,cmap). I wonder whether contents of rmap and cmap (or generally yyy, that set to xxx) pointing to are copied to somewhere in A (or xxx). In other words, shall I destroy 'yyy' after set to 'xxx' or I should not before finish using 'yyy' inside 'xxx'?

Other examples include KSPSetPC, PCCompositeAddPC(PC pc,PCType type), ISCreateGeneral, PCASMSetLocalSubdomains. I found that for PCASMSetLocalSubdomains the IS defining the subdomains are copied so we can destroy it afterwards. On the other hand, ISCreateGeneral forward a parameter to let user specify PetscCopyMode (Own_Pointer or Copy_Values).

Is there any general rule for these things? Thanks!

Answer 1

When there is a PetscCopyMode parameter, the behavior is explicit. We would like to be explicit in every instance, but that would become very cumbersome in the interface.

Create() gives back a new reference, whereas Get() returns a borrowed reference and should be given back using Restore().

The exceptions come up in Set() methods. They should all reference objects, and most do such as KSPSetPC(), however since this change was made relatively recently (and sometimes does not make as much sense), there are a few exceptions left. They will all eventually be documented/fixed. Please report any inconsistencies.The Get() methods generally return a borrowed reference since it is so cumbersome to destroy the object each time.

Answer 2

In general, the Set methods (and PETSc) pass-by-reference, so it is not safe to destroy the object that you have passed to the method. Methods such as PCASMSetLocalSubdomains are the exceptions, not the rules.