[petsc-dev] Get/Create fixes and questions

[Barry Smith]

1)
   The following five routines create objects that the user needs to call destroy on, the called object does not keep a reference

   MatGetFactor()
   MatGetVecs()
   KSPGetVecs()
   PetscOptionsGetViewer()
   DMDAGetRay()

   These should be changed to use Create

2)
   The routine 

   DMDASetGetMatrix()

    affects is DMCreateMatrix() so this should be    DMSetCreateMatrix()

3)
    The following routines 

    MatGetSubMatrix()
    MatGetRedundantMatrix() 
    MatGetMultiProcBlock()
    MatGetSubMatrices()
    MatGetSubMatricesParallel()


     create a matrix and do not keep a reference to it so likely should be changed to Create() BUT they all take
a MatReuse option so after the initial call do not create (yet another matrix). 

    Should these be changed to Create?

    If no one objects I will change 1-3 (and Jed will demand a deprecation warning that I might do if I can figure out how)

4) 
     a)  Many XXXXGetYYY() routines have a XXXXRestoreYYY()   

     b)  The rest of the XXXGetYYY() routines without XXXRestoreYYY() you are NOT suppose to call destroy on the objects (except for ones like in 1-3 that are miss-named)? 

     If we were starting PETSc today would we use a different word for the two cases, for example,

           XXXXObtainYYY() and XXXXRestoreYYY() and
          XXXXGetYYY()?

     I think Matt suggested somehow distinguishing the two types of Get in the manual pages somehow? Usually they say something somewhere on the page about calling the restore already, is that enough?


   Barry