Public handle types and small API consistency fixes

CHANGELOG.md

@@ -2,10 +2,21 @@
 
 ## Unreleased
 
+### Behaviour changes
+
+- A `LibPETSc` call whose arguments match no generated method, such as an `Int` where the library takes its scalar type, throws a `MethodError` naming the argument types, instead of an `ErrorException` with the text "no generated method for these argument types".
+- `library_info()` prints as the `NamedTuple` it returns. The report it printed came from a `show` method that also changed how any other `NamedTuple` with the same five field names printed. `PETSc.petsclibs` lists the libraries loaded in the session.
+
+### Added
+
+- The handle types are public API, with docstrings: the abstract types to annotate with (`AbstractPetscVec`, `AbstractPetscMat`, `AbstractPetscDM`, `AbstractKSP`, `AbstractPC`, `AbstractSNES`, `AbstractTS`, `AbstractPetscOptions`, `AbstractIS`, `AbstractAO`, `AbstractPF`, `AbstractTao`) and the handles `PetscDM`, `PC`, `IS`, `AO`, `PF` and `Tao`, all reachable as `PETSc.X`. `PETSc.realtype(petsclib)` gives the library's real type.
+
 ### Fixed
 
 - A dense matrix made with `PetscMat(petsclib, A::Matrix)` or `PetscMat(petsclib, m, n; type = :dense)` could lose its storage while a KSP still used it: once the Julia handle was collected, the array went with it, and the next solve read freed memory (a wrong answer or a PETSc zero-pivot error). The array now lives as long as the PETSc matrix, as it already did for CSR matrices and vectors on Julia arrays. `type = :dense` lets PETSc allocate the storage.
 - A `DMDA`, `DMStag` or `DMPlex` constructor, or `fe_create_default`, that threw inside PETSc (for example on `da_refine = "abc"`) left its options pushed on PETSc's options stack. Every object created afterwards read them, and the options could no longer be destroyed. The options are now popped whether or not the call throws.
+- `PETSc.scalartype` and `PETSc.inttype` are now the same functions as `LibPETSc.scalartype` and `LibPETSc.inttype`. They were two separate copies, so a method added to one was missing from the other.
+- `mul!`, `ksp \ b`, `ldiv!` and `solve!(x, ksp, b)` took only `PetscVec`, so a borrowed `VecPtr` gave a `MethodError` (`A * x` with a `VecPtr` failed inside). They take any vector handle.
 
 ## v0.5.3
 

docs/src/man/naming.md

@@ -1010,21 +1010,17 @@ The exceptions keep their underscore, because there it separates an inner worker
 | v0.4 | v0.5 |
 |---|---|
 | `set_petsclib` | `PetscLibType` constructor |
-| `library_info` | returns a `NamedTuple`, printed via `show` |
+| `library_info` | returns a `NamedTuple` |
 | `audit_petsc_file` | `audit_file` |
 | `set_library!`, `unset_library!` | unchanged ([§7](#7.-Mutation) global-state clause) |
 | `audit_walk`, `audit_targets`, `audit_report`, `audit_creator`, `audit_destroyer`, `audit_callee`, `audit_argnames`, `audit_isbroadcast`, `audit_hasparseerror` | unchanged (internal) |
 
 `library_info` printed a report and returned `nothing`, so its name promised data it never handed back.
-It now returns the values and gets a `show` method, which keeps the REPL output and makes the data reachable from tests:
+It now returns the values, so code and tests can read them:
 
 ```julia
 info = library_info()
 info.scalar          # Float64
-
-julia> library_info()
-Source  : LocalPreferences.toml
-Path    : /usr/lib/libpetsc.so
 ```
 
 ### Two consequences worth knowing

docs/src/man/utilities.md

@@ -11,6 +11,15 @@ Modules = [PETSc]
 Pages   = ["init.jl"]
 ```
 
+## Handle types
+
+Every PETSc object is held by a handle type with an abstract supertype, such as `PetscVec <: AbstractPetscVec`. Annotate with the abstract type to accept any handle of that kind. The handles below have no high-level layer of their own, apart from `destroy!`.
+
+```@autodocs
+Modules = [PETSc]
+Pages   = ["handles.jl"]
+```
+
 ## Destroying objects together
 
 On more than one process nothing frees a PETSc object but `destroy!`, called on every rank in the same order. `with_destroy` does that for every object registered with `track!` when its block ends.

scripts/renames.jl

@@ -449,6 +449,8 @@ const INTERNAL = Set{Symbol}([
     # other internals
     :check_initialized,
     :isdestroyable,
+    :destroy_handle!,
+    :destroy_options!,
     :as_petsc_vec,
     :csr_from_csc,
     :mat_seqaij_with_arrays,
@@ -539,6 +541,25 @@ const UNCHANGED_PUBLIC = Symbol[
     :set_residual!,
     :set_jacobian!,
     :set_jacobian_preconditioner!,
+    # handle types, defined in LibPETSc (naming.md §5.2, §5.5); new in v0.5.4
+    :AbstractPetscVec,
+    :AbstractPetscMat,
+    :AbstractPetscDM,
+    :AbstractKSP,
+    :AbstractPC,
+    :AbstractSNES,
+    :AbstractTS,
+    :AbstractPetscOptions,
+    :AbstractIS,
+    :AbstractAO,
+    :AbstractPF,
+    :AbstractTao,
+    :PetscDM,
+    :PC,
+    :IS,
+    :AO,
+    :PF,
+    :Tao,
     # vec.jl / mat.jl
     :VecPtr,
     :MatPtr,
@@ -634,6 +655,7 @@ const UNCHANGED_PUBLIC = Symbol[
     :finalize,
     :scalartype,
     :inttype,
+    :realtype,               # new in v0.5.4
     :library_info,
     :petsclibs,
     :set_library!,

src/LibPETSc_lib.jl

@@ -38,27 +38,31 @@ function Base.getproperty(petsclib::UnionPetscLibType, name::Symbol)
 end
 
 """
-    scalartype(petsclib::PetscLibType)
+    scalartype(petsclib)
+    scalartype(typeof(petsclib))
 
-return the scalar type for the associated `petsclib`
+The scalar type (`PetscScalar`) of the library `petsclib`, e.g. `Float64`.
 """
 scalartype(::PetscLibType{ST}) where {ST} = ST
 scalartype(::Type{PetscLib}) where {PetscLib <: PetscLibType{ST}} where {ST} =
     ST
 
 """
-    realtype(petsclib::PetscLibType)
+    realtype(petsclib)
+    realtype(typeof(petsclib))
 
-return the real type for the associated `petsclib`
+The real type (`PetscReal`) of the library `petsclib`: `real` of its scalar type,
+so `Float64` for both a `Float64` and a `ComplexF64` build.
 """
 realtype(::PetscLibType{ST}) where {ST} = real(ST)
 realtype(::Type{PetscLib}) where {PetscLib <: PetscLibType{ST}} where {ST} =
     real(ST)
 
 """
-    inttype(petsclib::PetscLibType)
+    inttype(petsclib)
+    inttype(typeof(petsclib))
 
-return the int type for the associated `petsclib`
+The integer type (`PetscInt`) of the library `petsclib`, e.g. `Int64`.
 """
 inttype(::PetscLibType{ST, IT}) where {ST, IT} = IT
 inttype(

src/autowrapped/AO_wrappers.jl

@@ -22,7 +22,7 @@ See also: `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
 $(_doc_external("AO/AOApplicationToPetsc"))
 """
 function AOApplicationToPetsc(petsclib::PetscLibType, ao::AbstractAO, n::Integer, ia::AbstractVector{<:Number})
-    error("AOApplicationToPetsc: no generated method for these argument types")
+    throw(MethodError(AOApplicationToPetsc, (petsclib, ao, n, ia)))
 end
 
 @for_petsc function AOApplicationToPetsc(petsclib::$UnionPetscLib, ao::AbstractAO, n::$PetscInt, ia::Vector{$PetscInt} )
@@ -61,7 +61,7 @@ See also: `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`,
 $(_doc_external("AO/AOApplicationToPetscIS"))
 """
 function AOApplicationToPetscIS(petsclib::PetscLibType, ao::AbstractAO, is::AbstractIS)
-    error("AOApplicationToPetscIS: no generated method for these argument types")
+    throw(MethodError(AOApplicationToPetscIS, (petsclib, ao, is)))
 end
 
 @for_petsc function AOApplicationToPetscIS(petsclib::$UnionPetscLib, ao::AbstractAO, is::AbstractIS )
@@ -100,7 +100,7 @@ See also: `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOAp
 $(_doc_external("AO/AOApplicationToPetscPermuteInt"))
 """
 function AOApplicationToPetscPermuteInt(petsclib::PetscLibType, ao::AbstractAO, block::Integer, array::AbstractVector{<:Number})
-    error("AOApplicationToPetscPermuteInt: no generated method for these argument types")
+    throw(MethodError(AOApplicationToPetscPermuteInt, (petsclib, ao, block, array)))
 end
 
 @for_petsc function AOApplicationToPetscPermuteInt(petsclib::$UnionPetscLib, ao::AbstractAO, block::$PetscInt, array::Vector{$PetscInt} )
@@ -139,7 +139,7 @@ See also: `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPets
 $(_doc_external("AO/AOApplicationToPetscPermuteReal"))
 """
 function AOApplicationToPetscPermuteReal(petsclib::PetscLibType, ao::AbstractAO, block::Integer, array::AbstractVector{<:Number})
-    error("AOApplicationToPetscPermuteReal: no generated method for these argument types")
+    throw(MethodError(AOApplicationToPetscPermuteReal, (petsclib, ao, block, array)))
 end
 
 @for_petsc function AOApplicationToPetscPermuteReal(petsclib::$UnionPetscLib, ao::AbstractAO, block::$PetscInt, array::Vector{$PetscReal} )
@@ -179,7 +179,7 @@ See also: `AO`, `AOView()`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`
 $(_doc_external("AO/AOCreate"))
 """
 function AOCreate(petsclib::PetscLibType, comm::MPI_Comm)
-    error("AOCreate: no generated method for these argument types")
+    throw(MethodError(AOCreate, (petsclib, comm)))
 end
 
 @for_petsc function AOCreate(petsclib::$UnionPetscLib, comm::MPI_Comm )
@@ -221,7 +221,7 @@ See also: `AO`, `AOCreateBasicIS()`, `AODestroy()`, `AOPetscToApplication()`, `A
 $(_doc_external("AO/AOCreateBasic"))
 """
 function AOCreateBasic(petsclib::PetscLibType, comm::MPI_Comm, napp::Integer, myapp::AbstractVector{<:Number}, mypetsc::AbstractVector{<:Number})
-    error("AOCreateBasic: no generated method for these argument types")
+    throw(MethodError(AOCreateBasic, (petsclib, comm, napp, myapp, mypetsc)))
 end
 
 @for_petsc function AOCreateBasic(petsclib::$UnionPetscLib, comm::MPI_Comm, napp::$PetscInt, myapp::Vector{$PetscInt}, mypetsc::Vector{$PetscInt} )
@@ -260,7 +260,7 @@ See also: `IS`, `AO`, `AOCreateBasic()`, `AODestroy()`
 $(_doc_external("AO/AOCreateBasicIS"))
 """
 function AOCreateBasicIS(petsclib::PetscLibType, isapp::AbstractIS, ispetsc::AbstractIS)
-    error("AOCreateBasicIS: no generated method for these argument types")
+    throw(MethodError(AOCreateBasicIS, (petsclib, isapp, ispetsc)))
 end
 
 @for_petsc function AOCreateBasicIS(petsclib::$UnionPetscLib, isapp::AbstractIS, ispetsc::AbstractIS )
@@ -302,7 +302,7 @@ See also: `AOCreateBasic()`, `AOCreateMappingIS()`, `AODestroy()`
 $(_doc_external("AO/AOCreateMapping"))
 """
 function AOCreateMapping(petsclib::PetscLibType, comm::MPI_Comm, napp::Integer, myapp::AbstractVector{<:Number}, mypetsc::AbstractVector{<:Number})
-    error("AOCreateMapping: no generated method for these argument types")
+    throw(MethodError(AOCreateMapping, (petsclib, comm, napp, myapp, mypetsc)))
 end
 
 @for_petsc function AOCreateMapping(petsclib::$UnionPetscLib, comm::MPI_Comm, napp::$PetscInt, myapp::Vector{$PetscInt}, mypetsc::Vector{$PetscInt} )
@@ -342,7 +342,7 @@ See also: `AOCreateBasic()`, `AOCreateMapping()`, `AODestroy()`
 $(_doc_external("AO/AOCreateMappingIS"))
 """
 function AOCreateMappingIS(petsclib::PetscLibType, isapp::AbstractIS, ispetsc::AbstractIS)
-    error("AOCreateMappingIS: no generated method for these argument types")
+    throw(MethodError(AOCreateMappingIS, (petsclib, isapp, ispetsc)))
 end
 
 @for_petsc function AOCreateMappingIS(petsclib::$UnionPetscLib, isapp::AbstractIS, ispetsc::AbstractIS )
@@ -383,7 +383,7 @@ See also: `AO`, `AOCreateMemoryScalableIS()`, `AODestroy()`, `AOPetscToApplicati
 $(_doc_external("AO/AOCreateMemoryScalable"))
 """
 function AOCreateMemoryScalable(petsclib::PetscLibType, comm::MPI_Comm, napp::Integer, myapp::AbstractVector{<:Number}, mypetsc::AbstractVector{<:Number})
-    error("AOCreateMemoryScalable: no generated method for these argument types")
+    throw(MethodError(AOCreateMemoryScalable, (petsclib, comm, napp, myapp, mypetsc)))
 end
 
 @for_petsc function AOCreateMemoryScalable(petsclib::$UnionPetscLib, comm::MPI_Comm, napp::$PetscInt, myapp::Vector{$PetscInt}, mypetsc::Vector{$PetscInt} )
@@ -422,7 +422,7 @@ See also: `AO`, `AOCreateBasicIS()`, `AOCreateMemoryScalable()`, `AODestroy()`
 $(_doc_external("AO/AOCreateMemoryScalableIS"))
 """
 function AOCreateMemoryScalableIS(petsclib::PetscLibType, isapp::AbstractIS, ispetsc::AbstractIS)
-    error("AOCreateMemoryScalableIS: no generated method for these argument types")
+    throw(MethodError(AOCreateMemoryScalableIS, (petsclib, isapp, ispetsc)))
 end
 
 @for_petsc function AOCreateMemoryScalableIS(petsclib::$UnionPetscLib, isapp::AbstractIS, ispetsc::AbstractIS )
@@ -457,7 +457,7 @@ See also: `AO`, `AOCreate()`
 $(_doc_external("AO/AODestroy"))
 """
 function AODestroy(petsclib::PetscLibType, ao::AbstractAO)
-    error("AODestroy: no generated method for these argument types")
+    throw(MethodError(AODestroy, (petsclib, ao)))
 end
 
 @for_petsc function AODestroy(petsclib::$UnionPetscLib, ao::AbstractAO )
@@ -488,7 +488,7 @@ See also: `AOInitializePackage()`, `PetscInitialize()`
 $(_doc_external("AO/AOFinalizePackage"))
 """
 function AOFinalizePackage(petsclib::PetscLibType)
-    error("AOFinalizePackage: no generated method for these argument types")
+    throw(MethodError(AOFinalizePackage, (petsclib, )))
 end
 
 @for_petsc function AOFinalizePackage(petsclib::$UnionPetscLib)
@@ -523,7 +523,7 @@ See also: `AO`, `AOType`, `AOSetType()`, `AOCreate()`, `PetscObjectTypeCompare()
 $(_doc_external("AO/AOGetType"))
 """
 function AOGetType(petsclib::PetscLibType, ao::AbstractAO)
-    error("AOGetType: no generated method for these argument types")
+    throw(MethodError(AOGetType, (petsclib, ao)))
 end
 
 @for_petsc function AOGetType(petsclib::$UnionPetscLib, ao::AbstractAO )
@@ -555,7 +555,7 @@ See also: `AOFinalizePackage()`, `PetscInitialize()`
 $(_doc_external("Sys/AOInitializePackage"))
 """
 function AOInitializePackage(petsclib::PetscLibType)
-    error("AOInitializePackage: no generated method for these argument types")
+    throw(MethodError(AOInitializePackage, (petsclib, )))
 end
 
 @for_petsc function AOInitializePackage(petsclib::$UnionPetscLib)
@@ -591,7 +591,7 @@ See also: `AOMappingHasPetscIndex()`, `AOCreateMapping()`, `AO`
 $(_doc_external("AO/AOMappingHasApplicationIndex"))
 """
 function AOMappingHasApplicationIndex(petsclib::PetscLibType, ao::AbstractAO, idex::Integer)
-    error("AOMappingHasApplicationIndex: no generated method for these argument types")
+    throw(MethodError(AOMappingHasApplicationIndex, (petsclib, ao, idex)))
 end
 
 @for_petsc function AOMappingHasApplicationIndex(petsclib::$UnionPetscLib, ao::AbstractAO, idex::$PetscInt )
@@ -630,7 +630,7 @@ See also: `AOMappingHasApplicationIndex()`, `AOCreateMapping()`
 $(_doc_external("AO/AOMappingHasPetscIndex"))
 """
 function AOMappingHasPetscIndex(petsclib::PetscLibType, ao::AbstractAO, idex::Integer)
-    error("AOMappingHasPetscIndex: no generated method for these argument types")
+    throw(MethodError(AOMappingHasPetscIndex, (petsclib, ao, idex)))
 end
 
 @for_petsc function AOMappingHasPetscIndex(petsclib::$UnionPetscLib, ao::AbstractAO, idex::$PetscInt )
@@ -672,7 +672,7 @@ See also: `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
 $(_doc_external("AO/AOPetscToApplication"))
 """
 function AOPetscToApplication(petsclib::PetscLibType, ao::AbstractAO, n::Integer, ia::AbstractVector{<:Number})
-    error("AOPetscToApplication: no generated method for these argument types")
+    throw(MethodError(AOPetscToApplication, (petsclib, ao, n, ia)))
 end
 
 @for_petsc function AOPetscToApplication(petsclib::$UnionPetscLib, ao::AbstractAO, n::$PetscInt, ia::Vector{$PetscInt} )
@@ -711,7 +711,7 @@ See also: `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`,
 $(_doc_external("AO/AOPetscToApplicationIS"))
 """
 function AOPetscToApplicationIS(petsclib::PetscLibType, ao::AbstractAO, is::AbstractIS)
-    error("AOPetscToApplicationIS: no generated method for these argument types")
+    throw(MethodError(AOPetscToApplicationIS, (petsclib, ao, is)))
 end
 
 @for_petsc function AOPetscToApplicationIS(petsclib::$UnionPetscLib, ao::AbstractAO, is::AbstractIS )
@@ -750,7 +750,7 @@ See also: `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPets
 $(_doc_external("AO/AOPetscToApplicationPermuteInt"))
 """
 function AOPetscToApplicationPermuteInt(petsclib::PetscLibType, ao::AbstractAO, block::Integer, array::AbstractVector{<:Number})
-    error("AOPetscToApplicationPermuteInt: no generated method for these argument types")
+    throw(MethodError(AOPetscToApplicationPermuteInt, (petsclib, ao, block, array)))
 end
 
 @for_petsc function AOPetscToApplicationPermuteInt(petsclib::$UnionPetscLib, ao::AbstractAO, block::$PetscInt, array::Vector{$PetscInt} )
@@ -789,7 +789,7 @@ See also: `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPets
 $(_doc_external("AO/AOPetscToApplicationPermuteReal"))
 """
 function AOPetscToApplicationPermuteReal(petsclib::PetscLibType, ao::AbstractAO, block::Integer, array::AbstractVector{<:Number})
-    error("AOPetscToApplicationPermuteReal: no generated method for these argument types")
+    throw(MethodError(AOPetscToApplicationPermuteReal, (petsclib, ao, block, array)))
 end
 
 @for_petsc function AOPetscToApplicationPermuteReal(petsclib::$UnionPetscLib, ao::AbstractAO, block::$PetscInt, array::Vector{$PetscReal} )
@@ -823,7 +823,7 @@ See also: `AO`, `AOType`, `AOCreate()`, `AORegisterAll()`, `AOBASIC`, `AOADVANCE
 $(_doc_external("AO/AORegister"))
 """
 function AORegister(petsclib::PetscLibType, sname::String, fnc::external)
-    error("AORegister: no generated method for these argument types")
+    throw(MethodError(AORegister, (petsclib, sname, fnc)))
 end
 
 @for_petsc function AORegister(petsclib::$UnionPetscLib, sname::String, fnc::external )
@@ -853,7 +853,7 @@ See also: `AO`, `AOType`, `AORegister()`, `AORegisterDestroy()`
 $(_doc_external("AO/AORegisterAll"))
 """
 function AORegisterAll(petsclib::PetscLibType)
-    error("AORegisterAll: no generated method for these argument types")
+    throw(MethodError(AORegisterAll, (petsclib, )))
 end
 
 @for_petsc function AORegisterAll(petsclib::$UnionPetscLib)
@@ -888,7 +888,7 @@ See also: `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplicatio
 $(_doc_external("AO/AOSetFromOptions"))
 """
 function AOSetFromOptions(petsclib::PetscLibType, ao::AbstractAO)
-    error("AOSetFromOptions: no generated method for these argument types")
+    throw(MethodError(AOSetFromOptions, (petsclib, ao)))
 end
 
 @for_petsc function AOSetFromOptions(petsclib::$UnionPetscLib, ao::AbstractAO )
@@ -923,7 +923,7 @@ See also: `AO`, `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplic
 $(_doc_external("AO/AOSetIS"))
 """
 function AOSetIS(petsclib::PetscLibType, ao::AbstractAO, isapp::AbstractIS, ispetsc::AbstractIS)
-    error("AOSetIS: no generated method for these argument types")
+    throw(MethodError(AOSetIS, (petsclib, ao, isapp, ispetsc)))
 end
 
 @for_petsc function AOSetIS(petsclib::$UnionPetscLib, ao::AbstractAO, isapp::AbstractIS, ispetsc::AbstractIS )
@@ -960,7 +960,7 @@ See also: `AO`, `AOType`, `AOCreateBasic()`, `AOCreateMemoryScalable()`, `AOGetT
 $(_doc_external("AO/AOSetType"))
 """
 function AOSetType(petsclib::PetscLibType, ao::AbstractAO, method::String)
-    error("AOSetType: no generated method for these argument types")
+    throw(MethodError(AOSetType, (petsclib, ao, method)))
 end
 
 @for_petsc function AOSetType(petsclib::$UnionPetscLib, ao::AbstractAO, method::String )
@@ -997,7 +997,7 @@ See also: `AO`, `PetscViewer`, `PetscViewerASCIIOpen()`, `AOViewFromOptions()`
 $(_doc_external("AO/AOView"))
 """
 function AOView(petsclib::PetscLibType, ao::AbstractAO, viewer::PetscViewer)
-    error("AOView: no generated method for these argument types")
+    throw(MethodError(AOView, (petsclib, ao, viewer)))
 end
 
 @for_petsc function AOView(petsclib::$UnionPetscLib, ao::AbstractAO, viewer::PetscViewer )
@@ -1035,7 +1035,7 @@ See also: `AO`, `AOView()`, `PetscObjectViewFromOptions()`, `AOCreate()`
 $(_doc_external("AO/AOViewFromOptions"))
 """
 function AOViewFromOptions(petsclib::PetscLibType, ao::AbstractAO, obj, name::String)
-    error("AOViewFromOptions: no generated method for these argument types")
+    throw(MethodError(AOViewFromOptions, (petsclib, ao, obj, name)))
 end
 
 @for_petsc function AOViewFromOptions(petsclib::$UnionPetscLib, ao::AbstractAO, obj, name::String )