From 533aa8d34cf7bba299a720dcae12a3cd17af09c1 Mon Sep 17 00:00:00 2001 From: Patrick Sanan Date: Mon, 23 May 2016 10:18:26 +0200 Subject: [PATCH 1/2] Dev Manual: add blurb on PETSC_INTERN and PETSC_EXTERN Adds a blurb to the "naming" section of the dev manual explaining the meaning of PETSC_INTERN and PETSC_EXTERN and giving some examples. Names of functions and classes are typeset using \trl{}. --- src/docs/tex/manual/developers.tex | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/docs/tex/manual/developers.tex b/src/docs/tex/manual/developers.tex index a758824..0de792e 100644 --- a/src/docs/tex/manual/developers.tex +++ b/src/docs/tex/manual/developers.tex @@ -152,6 +152,15 @@ We use several conventions: for example, ISInvertPermutation(), MatMult() or KSPGMRESSetRestart(). \item Functions that PETSc provides as defaults for user provideable functions end with \trl{Default} (for example, \trl{KSPMonitorDefault()} or \trl{PetscSignalHandlerDefault()}) \item Options database keys are lower case, have an underscore between words and match the function name associated with the option without the word {\em set} or {\em get}. For example, \trl{-ksp_gmres_restart}. +\item Library functions should be declared \trl{PETSC_INTERN} if they are intended to be visible only within a single shared library. +They should be declared \trl{PETSC_EXTERN} if intended to be visible across shared libraries. +Note that PETSc can be configured to build a separate shared library for each top-level class (\trl{Mat}, \trl{Vec}, \trl{KSP},etc.) and that plugin implementations of these classes can be included as separate shared libraries; thus, private functions may be marked \trl{PETSC_EXTERN}. +For example, +\begin{itemize} +\item \trl{MatStashCreate_Private} is marked \trl{PETSC_INTERN} as it is used across compilation units, but only within the \trl{Mat} package. +\item All functions, such as \trl{KSP_Create()}, included in the public headers \trl{include/petsc*.h}) should be marked \trl{PETSC_EXTERN}. +\item \trl{MatHeaderReplace()} is not intended for users (it is in \trl{include/petsc/private/matimpl.h}) but is marked \trl{PETSC_EXTERN} since it is used both by implementations of the \trl{Mat} class (which could be defined in plugin implementations) and by functions in the \trl{DM} and \trl{KSP} packages. +\end{itemize} \end{itemize} \section{Coding Conventions and Style Guide} -- 2.7.1