libMesh::WrappedPetsc< T > Struct Template Reference

#include <wrapped_petsc.h>

Public Member Functions
	WrappedPetsc ()
	Default constructor. More...
	WrappedPetsc (T obj_in)
	Constructor which initializes obj to a specific passed-in value. More...
	~WrappedPetsc ()
	Destructor. More...
void	reset_to_zero ()
	Calls destroy() and sets the managed object to nullptr. More...
	WrappedPetsc (const WrappedPetsc &other)=delete
	Copy constructor and copy assignment operator. More...
WrappedPetsc &	operator= (const WrappedPetsc &)=delete
	WrappedPetsc (WrappedPetsc &&other) noexcept
	Move constructor. More...
WrappedPetsc &	operator= (WrappedPetsc &&other) noexcept
	Move-assignment operator. More...
T *	get ()
	operator T () const
	User-defined conversion function. More...
T &	operator* ()
	The "dereferencing" operator. More...
	operator bool () const
	User-defined conversion to bool. More...
void	destroy ()
	Must be specialized to call the appropriate XXXDestroy() routine in order for a WrappedPetsc<T> object to be instantiated. More...
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()
template<>
void	destroy ()

Private Attributes
T	obj

Detailed Description

template<typename T>
struct libMesh::WrappedPetsc< T >

Definition at line 34 of file wrapped_petsc.h.

Constructor & Destructor Documentation

WrappedPetsc() [1/4]

template<typename T>

libMesh::WrappedPetsc< T >::WrappedPetsc ( )

inline

Default constructor.

This should mimic the way that we normally write e.g. KSP ksp; and then proceed to use ksp in different PETSc routines. That is, obj is not initialized to any particular value.

Definition at line 43 of file wrapped_petsc.h.

: obj() {}

WrappedPetsc() [2/4]

template<typename T>

libMesh::WrappedPetsc< T >::WrappedPetsc ( T  obj_in )

inline

Constructor which initializes obj to a specific passed-in value.

This mimics code in which we explicitly create a PETSc object via IS is = NULL; Technically one could pass any pointer value in here, but it usually only makes sense to pass nullptr.

Definition at line 52 of file wrapped_petsc.h.

: obj(obj_in) {}

~WrappedPetsc()

template<typename T>

libMesh::WrappedPetsc< T >::~WrappedPetsc ( )

inline

Destructor.

Just calls destroy().

Definition at line 57 of file wrapped_petsc.h.

  {
    destroy();
  }

WrappedPetsc() [3/4]

template<typename T>

libMesh::WrappedPetsc< T >::WrappedPetsc ( const WrappedPetsc< T > &  other )

delete

Copy constructor and copy assignment operator.

These are deleted since I don't think we can safely shallow copy PETSc objects like KSP and Vec, which are internally reference-counted pointers and probably don't do the right thing if they are shallow-copied.

WrappedPetsc() [4/4]

template<typename T>

libMesh::WrappedPetsc< T >::WrappedPetsc ( WrappedPetsc< T > &&  other )

inlinenoexcept

Move constructor.

We could almost default this, but we need to set other.obj to nullptr so that when it is subsequently Destroy()ed it's just a no-op rather than messing up the reference count or trying to double-free memory.

Definition at line 91 of file wrapped_petsc.h.

    : obj(other.obj)
  {
    other.obj = nullptr;
  }

Member Function Documentation

destroy() [1/13]

template<>

void libMesh::WrappedPetsc< Vec >::destroy

(

)

Definition at line 57 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, VecDestroy(&obj));
}

destroy() [2/13]

template<>

void libMesh::WrappedPetsc< KSP >::destroy

(

)

Definition at line 64 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, KSPDestroy(&obj));
}

destroy() [3/13]

template<>

void libMesh::WrappedPetsc< IS >::destroy

(

)

Definition at line 71 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, ISDestroy(&obj));
}

destroy() [4/13]

template<>

void libMesh::WrappedPetsc< Mat >::destroy

(

)

Definition at line 78 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, MatDestroy(&obj));
}

destroy() [5/13]

template<>

void libMesh::WrappedPetsc< VecScatter >::destroy

(

)

Definition at line 85 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, VecScatterDestroy(&obj));
}

destroy() [6/13]

template<>

void libMesh::WrappedPetsc< PetscViewer >::destroy

(

)

Definition at line 92 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, PetscViewerDestroy(&obj));
}

destroy() [7/13]

template<>

void libMesh::WrappedPetsc< MatNullSpace >::destroy

(

)

Definition at line 99 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, MatNullSpaceDestroy(&obj));
}

destroy() [8/13]

template<>

void libMesh::WrappedPetsc< DM >::destroy

(

)

Definition at line 106 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, DMDestroy(&obj));
}

destroy() [9/13]

template<>

void libMesh::WrappedPetsc< MatPartitioning >::destroy

(

)

Definition at line 113 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, MatPartitioningDestroy(&obj));
}

destroy() [10/13]

template<>

void libMesh::WrappedPetsc< SNES >::destroy

(

)

Definition at line 120 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, SNESDestroy(&obj));
}

destroy() [11/13]

template<>

void libMesh::WrappedPetsc< PC >::destroy

(

)

Definition at line 127 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, PCDestroy(&obj));
}

destroy() [12/13]

template<>

void libMesh::WrappedPetsc< PetscSection >::destroy

(

)

Definition at line 134 of file wrapped_petsc.C.

{
  LibmeshPetscCallA(PETSC_COMM_SELF, PetscSectionDestroy(&obj));
}

destroy() [13/13]

template<typename T>

void libMesh::WrappedPetsc< T >::destroy

(

)

Must be specialized to call the appropriate XXXDestroy() routine in order for a WrappedPetsc<T> object to be instantiated.

We could try to do extra error checking in destroy() as shown below, but note that: 1.) destroy() is called from destructors, sometimes during stack unwinding. If there's an error code returned from XXXDestroy(), then our only option is to immediately terminate the program, which would then kill any chance of recovering from the exception. 2.) It's not always safe to call non-Destroy() functions on PETSc objects which are about to be Destroy()ed, that is, we would have to check for nullptr, etc. which would lead to more complexity, and more code.

One possible approach for extra error checking with immediate abort on error:

MPI_Comm comm; PetscObjectGetComm((PetscObject)(&obj), &comm); PetscErrorCode ierr = Type ## Destroy(&obj); CHKERRABORT(comm, ierr);

Referenced by libMesh::PetscDiffSolver::clear(), libMesh::WrappedPetsc< SNES >::reset_to_zero(), and libMesh::WrappedPetsc< SNES >::~WrappedPetsc().

get()

template<typename T>

T* libMesh::WrappedPetsc< T >::get ( )

inline

Returns

pointer to the managed object This is used to mimic code such as: KSP ksp; KSPCreate(comm, &ksp); Since taking the address of the wrapping object doesn't make sense in this context.

Definition at line 117 of file wrapped_petsc.h.

Referenced by libMesh::PetscMatrix< T >::_get_submatrix(), libMesh::PetscVector< libMesh::Number >::create_subvector(), libMesh::PetscVector< libMesh::Number >::get_subvector(), libMesh::PetscNonlinearSolver< Number >::init(), libMesh::PetscVector< libMesh::Number >::localize(), libMesh::PetscVector< libMesh::Number >::localize_to_one(), libMesh::PetscMatrix< T >::print_matlab(), libMesh::PetscVector< libMesh::Number >::print_matlab(), libMesh::Partitioner::set_interface_node_processor_ids_petscpartitioner(), libMesh::PetscDiffSolver::setup_petsc_data(), libMesh::PetscLinearSolver< Number >::shell_solve_common(), libMesh::PetscNonlinearSolver< Number >::solve(), and libMesh::PetscLinearSolver< Number >::solve_base().

{ return &obj; }

operator bool()

template<typename T>

libMesh::WrappedPetsc< T >::operator bool ( ) const

inline

User-defined conversion to bool.

This is intended to mimic code like: IS is = nullptr; ... if (!is) ... Note that this comparison is thus concerned with obj itself and not &obj.

Definition at line 147 of file wrapped_petsc.h.

{ return obj != nullptr; }

operator T()

template<typename T>

libMesh::WrappedPetsc< T >::operator T ( ) const

inline

User-defined conversion function.

We provide non-const access to the underlying T object even when the "this" object is considered const, since PETSc APIs which are "logically const" typically still take non-const parameters.

Definition at line 125 of file wrapped_petsc.h.

References libMesh::WrappedPetsc< T >::obj.

{ return obj; }

operator*()

template<typename T>

T& libMesh::WrappedPetsc< T >::operator* ( )

inline

The "dereferencing" operator.

Returns a reference to the managed object. This is needed for some situations in which the user-defined conversion operator doesn't work, for example with C-style casts: KSP ksp; ... PetscObjectSetOptionsPrefix((PetscObject)(*ksp), "balance_");

Definition at line 136 of file wrapped_petsc.h.

{ return obj; }

operator=() [1/2]

template<typename T>

WrappedPetsc& libMesh::WrappedPetsc< T >::operator= ( const WrappedPetsc< T > &  )

delete

operator=() [2/2]

template<typename T>

WrappedPetsc& libMesh::WrappedPetsc< T >::operator= ( WrappedPetsc< T > &&  other )

inlinenoexcept

Move-assignment operator.

Use move-construct-and-swap idiom instead of defaulting since we want to make sure our move constructor leaves the passed-in object in a Destroy()able state.

Definition at line 102 of file wrapped_petsc.h.

  {
    WrappedPetsc tmp(std::move(other));
    std::swap(tmp, *this);
    return *this;
  }

reset_to_zero()

template<typename T>

void libMesh::WrappedPetsc< T >::reset_to_zero ( )

inline

Calls destroy() and sets the managed object to nullptr.

As far as I can tell, setting obj to nullptr is not done by the various XXXDestroy() routines of PETSc, so we also don't do this in the wrapping class's destructor, however, there are situations where it is sometimes useful to both call the relevant XXXDestroy() function and reset the pointer, hence the need for this function.

Definition at line 70 of file wrapped_petsc.h.

  {
    destroy();
    obj = nullptr;
  }

Member Data Documentation

obj

template<typename T>

T libMesh::WrappedPetsc< T >::obj

private

Definition at line 175 of file wrapped_petsc.h.

Referenced by libMesh::WrappedPetsc< SNES >::get(), libMesh::WrappedPetsc< SNES >::operator bool(), libMesh::WrappedPetsc< T >::operator T(), libMesh::WrappedPetsc< SNES >::operator*(), and libMesh::WrappedPetsc< SNES >::reset_to_zero().

---

The documentation for this struct was generated from the following file:

• include/numerics/wrapped_petsc.h