Skip to main content
`Ctrl`+`K`

# PetscHeaderCreate

Creates a raw PETSc object of a particular class

## Synopsis

    #include <petsc/private/petscimpl.h>
    PetscErrorCode PetscHeaderCreate(PetscObject h, PetscClassId classid, const char class_name[], const char descr[], const char mansec[], MPI_Comm comm, PetscObjectDestroyFn * destroy, PetscObjectViewFn * view)

Collective

## Input Parameters

- classid - The classid associated with this object (for example `VEC_CLASSID`)

- class_name - String name of class; should be static (for example “Vec”), may be `PETSC_NULLPTR`

- descr - String containing short description; should be static (for example “Vector”), may be `PETSC_NULLPTR`

- mansec - String indicating section in manual pages; should be static (for example “Vec”), may be `PETSC_NULLPTR`

- comm - The MPI Communicator

- destroy - The destroy routine for this object (for example `VecDestroy()`)

- view - The view routine for this object (for example `VecView()`), may be `PETSC_NULLPTR`

## Output Parameter

- h - The newly created `PetscObject`

## Notes

Can only be used to create a `PetscObject`. A `PetscObject` is defined as a pointer to a C/C++ structure which satisfies all of the following:

1. The first member of the structure must be a `_p_PetscObject`.

2. C++ structures must be “Standard Layout”. Generally speaking a standard layout class:

- Has no virtual functions or base classes.

- Has only standard layout non-static members (if any).

- Has only standard layout base classes (if any).

See https://en.cppreference.com/w/cpp/language/classes#Standard-layout_class for further information.

## Example Usage

Existing `PetscObject`s may be easily created as shown. Unless otherwise stated, a particular objects `destroy` and `view` functions are exactly `<OBJECT_TYPE>Destroy()` and `<OBJECT_TYPE>View()`.

      Vec v;

      PetscHeaderCreate(v, VEC_CLASSID, "Vec", "A distributed vector class", "Vec", PETSC_COMM_WORLD, VecDestroy, VecView);

It is possible to create custom `PetscObject`s, note however that they must abide by the restrictions set forth above.

      // OK, first member of C structure is _p_PetscObject
      struct MyCPetscObject_s
      {
        _p_PetscObject header;
        int            some_data;
      };
      typedef struct *MyCPetscObject_s MyCPetscObject;

      PetscErrorCode MyObjectDestroy(MyObject *);
      PetscErrorCode MyObjectView(MyObject);

      MyCPetscObject obj;

      // assume MY_PETSC_CLASSID is already registered
      PetscHeaderCreate(obj, MY_PETSC_CLASSID, "MyObject", "A custom PetscObject", PETSC_NULLPTR, PETSC_COMM_SELF, MyObjectDestroy, MyObjectView);

      // OK, only destroy function must be given, all others may be NULL
      PetscHeaderCreate(obj, MY_PETSC_CLASSID, PETSC_NULLPTR, PETSC_NULLPTR, PETSC_NULLPTR, PETSC_COMM_SELF, MyObjectDestroy, PETSC_NULLPTR);

      // ERROR must be a single-level pointer
      PetscHeaderCreate(&obj, ...);

Illustrating proper construction from C++:

      // ERROR, class is not standard layout, first member must be publicly accessible
      class BadCppPetscObject
      {
        _p_PetscObject header;
      };

      // ERROR, class is not standard layout, has a virtual function and virtual inheritance
      class BadCppPetscObject2 : virtual BaseClass
      {
      public:
        _p_PetscObject header;

        virtual void foo();
      };

      // ERROR, class is not standard layout! Has non-standard layout member
      class BadCppPetscObject2
      {
      public:
        _p_PetscObject    header;
        BadCppPetscObject non_standard_layout;
      };

      // OK, class is standard layout!
      class GoodCppPetscObject;
      using MyCppObject = GoodCppPetscObject *;

      // OK, non-virtual inheritance of other standard layout class does not affect layout
      class GoodCppPetscObject : StandardLayoutClass
      {
      public:
        // OK, non standard layout member is static, does not affect layout
        static BadCppPetscObject non_standard_layout;

        // OK, first non-static member is _p_PetscObject
        _p_PetscObject header;

         // OK, non-virtual member functions do not affect class layout
        void foo();

        // OK, may use "member" functions for destroy and view so long as they are static
        static PetscErrorCode destroy(MyCppObject *);
        static PetscErrorCode view(MyCppObject);
      };

      // OK, usage via pointer
      MyObject obj;

      PetscHeaderCreate(obj, MY_PETSC_CLASSID, "MyObject", "A custom C++ PetscObject", nullptr, PETSC_COMM_SELF, GoodCppPetscObject::destroy, GoodCppPetscObject::view);

## See Also

`PetscObject`, `PetscHeaderDestroy()`, `PetscClassIdRegister()`

## Level

developer

## Location

include/petsc/private/petscimpl.h

## Examples

src/ts/tutorials/ex14.c
src/snes/tutorials/ex48.c

Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages