wrap_gen: add wrappers supporting Julia objects

- add Handle{} (based on PR #29) that provides automatic memory
  management for CVODEMem, KINMem and IDAMem
- add NVector wrapper (based on PR #29) that provides automatic memory
  management and conversion to/from Julia arrays for N_Vector
- generate wrapper functions accepting Julia objects
  (Handles, NVectors, Vectors, Arrays);
- the names of the "bare" wrappers that pass the arguments as-is are
  mangled by "__" (to avoid stack overflow if argument types are
  incompatible)

Author: alyst

src/Sundials.jl

@@ -0,0 +1,58 @@
+##################################################################
+#
+# Pointers to Sundials objects
+#
+##################################################################
+
+"""
+    Base type for dummy placeholders that help to
+    providing typed pointers for Sundials objects
+    (KINSOL, CVODE, IDA).
+
+    See `Handle`.
+"""
+abstract AbstractSundialsObject
+
+immutable CVODEMem <: AbstractSundialsObject end
+typealias CVODEMemPtr Ptr{CVODEMem}
+
+immutable IDAMem <: AbstractSundialsObject end
+typealias IDAMemPtr Ptr{IDAMem}
+
+immutable KINMem <: AbstractSundialsObject end
+typealias KINMemPtr Ptr{KINMem}
+
+"""
+   Handle for Sundials objects (CVODE, IDA, KIN).
+
+   Wraps the reference to the pointer to the Sundials object.
+   Manages automatic destruction of the referenced objects when it is
+   no longer in use.
+"""
+immutable Handle{T <: AbstractSundialsObject}
+    ptr_ref::Ref{Ptr{T}} # pointer to a pointer
+
+    function Base.call{T}(::Type{Handle}, ptr::Ptr{T})
+        h = new{T}(Ref{Ptr{T}}(ptr))
+        finalizer(h.ptr_ref, release_handle)
+        return h
+    end
+end
+
+Base.convert{T}(::Type{Ptr{T}}, h::Handle{T}) = h.ptr_ref[]
+Base.convert{T}(::Type{Ptr{Ptr{T}}}, h::Handle{T}) = convert(Ptr{Ptr{T}}, h.ptr_ref[])
+
+release_handle{T}(ptr_ref::Ref{Ptr{T}}) = throw(MethodError("Freeing objects of type $T not supported"))
+release_handle(ptr_ref::Ref{Ptr{KINMem}}) = KINSOLFree(ptr_ref)
+release_handle(ptr_ref::Ref{Ptr{CVODEMem}}) = CVodeFree(ptr_ref)
+release_handle(ptr_ref::Ref{Ptr{IDAMem}}) = IDAFree(ptr_ref)
+
+##################################################################
+#
+# Convenience typealiases for Sundials handles
+#
+##################################################################
+
+typealias CVODEh Handle{CVODEMem}
+typealias KINh Handle{KINMem}
+typealias IDAh Handle{IDAMem}

src/cvode.jl

@@ -17,118 +17,174 @@ function N_VMake_Serial(vec_length::Clong,v_data::Ptr{realtype})
     ccall((:N_VMake_Serial,libsundials_nvecserial),N_Vector,(Clong,Ptr{realtype}),vec_length,v_data)
 end
 
-function N_VCloneVectorArray_Serial(count::Cint,w::N_Vector)
+function __N_VCloneVectorArray_Serial(count::Cint,w::N_Vector)
     ccall((:N_VCloneVectorArray_Serial,libsundials_nvecserial),Ptr{N_Vector},(Cint,N_Vector),count,w)
 end
 
-function N_VCloneVectorArrayEmpty_Serial(count::Cint,w::N_Vector)
+N_VCloneVectorArray_Serial(count,w) = __N_VCloneVectorArray_Serial(count,convert(N_Vector,w))
+
+function __N_VCloneVectorArrayEmpty_Serial(count::Cint,w::N_Vector)
     ccall((:N_VCloneVectorArrayEmpty_Serial,libsundials_nvecserial),Ptr{N_Vector},(Cint,N_Vector),count,w)
 end
 
+N_VCloneVectorArrayEmpty_Serial(count,w) = __N_VCloneVectorArrayEmpty_Serial(count,convert(N_Vector,w))
+
 function N_VDestroyVectorArray_Serial(vs::Ptr{N_Vector},count::Cint)
     ccall((:N_VDestroyVectorArray_Serial,libsundials_nvecserial),Void,(Ptr{N_Vector},Cint),vs,count)
 end
 
-function N_VPrint_Serial(v::N_Vector)
+function __N_VPrint_Serial(v::N_Vector)
     ccall((:N_VPrint_Serial,libsundials_nvecserial),Void,(N_Vector,),v)
 end
 
-function N_VCloneEmpty_Serial(w::N_Vector)
+N_VPrint_Serial(v) = __N_VPrint_Serial(convert(N_Vector,v))
+
+function __N_VCloneEmpty_Serial(w::N_Vector)
     ccall((:N_VCloneEmpty_Serial,libsundials_nvecserial),N_Vector,(N_Vector,),w)
 end
 
-function N_VClone_Serial(w::N_Vector)
+N_VCloneEmpty_Serial(w) = __N_VCloneEmpty_Serial(convert(N_Vector,w))
+
+function __N_VClone_Serial(w::N_Vector)
     ccall((:N_VClone_Serial,libsundials_nvecserial),N_Vector,(N_Vector,),w)
 end
 
-function N_VDestroy_Serial(v::N_Vector)
+N_VClone_Serial(w) = __N_VClone_Serial(convert(N_Vector,w))
+
+function __N_VDestroy_Serial(v::N_Vector)
     ccall((:N_VDestroy_Serial,libsundials_nvecserial),Void,(N_Vector,),v)
 end
 
-function N_VSpace_Serial(v::N_Vector,lrw::Ptr{Clong},liw::Ptr{Clong})
+N_VDestroy_Serial(v) = __N_VDestroy_Serial(convert(N_Vector,v))
+
+function __N_VSpace_Serial(v::N_Vector,lrw::Ptr{Clong},liw::Ptr{Clong})
     ccall((:N_VSpace_Serial,libsundials_nvecserial),Void,(N_Vector,Ptr{Clong},Ptr{Clong}),v,lrw,liw)
 end
 
-function N_VGetArrayPointer_Serial(v::N_Vector)
+N_VSpace_Serial(v,lrw,liw) = __N_VSpace_Serial(convert(N_Vector,v),pointer(lrw),pointer(liw))
+
+function __N_VGetArrayPointer_Serial(v::N_Vector)
     ccall((:N_VGetArrayPointer_Serial,libsundials_nvecserial),Ptr{realtype},(N_Vector,),v)
 end
 
-function N_VSetArrayPointer_Serial(v_data::Ptr{realtype},v::N_Vector)
+N_VGetArrayPointer_Serial(v) = __N_VGetArrayPointer_Serial(convert(N_Vector,v))
+
+function __N_VSetArrayPointer_Serial(v_data::Ptr{realtype},v::N_Vector)
     ccall((:N_VSetArrayPointer_Serial,libsundials_nvecserial),Void,(Ptr{realtype},N_Vector),v_data,v)
 end
 
-function N_VLinearSum_Serial(a::realtype,x::N_Vector,b::realtype,y::N_Vector,z::N_Vector)
+N_VSetArrayPointer_Serial(v_data,v) = __N_VSetArrayPointer_Serial(pointer(v_data),convert(N_Vector,v))
+
+function __N_VLinearSum_Serial(a::realtype,x::N_Vector,b::realtype,y::N_Vector,z::N_Vector)
     ccall((:N_VLinearSum_Serial,libsundials_nvecserial),Void,(realtype,N_Vector,realtype,N_Vector,N_Vector),a,x,b,y,z)
 end
 
-function N_VConst_Serial(c::realtype,z::N_Vector)
+N_VLinearSum_Serial(a,x,b,y,z) = __N_VLinearSum_Serial(a,convert(N_Vector,x),b,convert(N_Vector,y),convert(N_Vector,z))
+
+function __N_VConst_Serial(c::realtype,z::N_Vector)
     ccall((:N_VConst_Serial,libsundials_nvecserial),Void,(realtype,N_Vector),c,z)
 end
 
-function N_VProd_Serial(x::N_Vector,y::N_Vector,z::N_Vector)
+N_VConst_Serial(c,z) = __N_VConst_Serial(c,convert(N_Vector,z))
+
+function __N_VProd_Serial(x::N_Vector,y::N_Vector,z::N_Vector)
     ccall((:N_VProd_Serial,libsundials_nvecserial),Void,(N_Vector,N_Vector,N_Vector),x,y,z)
 end
 
-function N_VDiv_Serial(x::N_Vector,y::N_Vector,z::N_Vector)
+N_VProd_Serial(x,y,z) = __N_VProd_Serial(convert(N_Vector,x),convert(N_Vector,y),convert(N_Vector,z))
+
+function __N_VDiv_Serial(x::N_Vector,y::N_Vector,z::N_Vector)
     ccall((:N_VDiv_Serial,libsundials_nvecserial),Void,(N_Vector,N_Vector,N_Vector),x,y,z)
 end
 
-function N_VScale_Serial(c::realtype,x::N_Vector,z::N_Vector)
+N_VDiv_Serial(x,y,z) = __N_VDiv_Serial(convert(N_Vector,x),convert(N_Vector,y),convert(N_Vector,z))
+
+function __N_VScale_Serial(c::realtype,x::N_Vector,z::N_Vector)
     ccall((:N_VScale_Serial,libsundials_nvecserial),Void,(realtype,N_Vector,N_Vector),c,x,z)
 end
 
-function N_VAbs_Serial(x::N_Vector,z::N_Vector)
+N_VScale_Serial(c,x,z) = __N_VScale_Serial(c,convert(N_Vector,x),convert(N_Vector,z))
+
+function __N_VAbs_Serial(x::N_Vector,z::N_Vector)
     ccall((:N_VAbs_Serial,libsundials_nvecserial),Void,(N_Vector,N_Vector),x,z)
 end
 
-function N_VInv_Serial(x::N_Vector,z::N_Vector)
+N_VAbs_Serial(x,z) = __N_VAbs_Serial(convert(N_Vector,x),convert(N_Vector,z))
+
+function __N_VInv_Serial(x::N_Vector,z::N_Vector)
     ccall((:N_VInv_Serial,libsundials_nvecserial),Void,(N_Vector,N_Vector),x,z)
 end
 
-function N_VAddConst_Serial(x::N_Vector,b::realtype,z::N_Vector)
+N_VInv_Serial(x,z) = __N_VInv_Serial(convert(N_Vector,x),convert(N_Vector,z))
+
+function __N_VAddConst_Serial(x::N_Vector,b::realtype,z::N_Vector)
     ccall((:N_VAddConst_Serial,libsundials_nvecserial),Void,(N_Vector,realtype,N_Vector),x,b,z)
 end
 
-function N_VDotProd_Serial(x::N_Vector,y::N_Vector)
+N_VAddConst_Serial(x,b,z) = __N_VAddConst_Serial(convert(N_Vector,x),b,convert(N_Vector,z))
+
+function __N_VDotProd_Serial(x::N_Vector,y::N_Vector)
     ccall((:N_VDotProd_Serial,libsundials_nvecserial),realtype,(N_Vector,N_Vector),x,y)
 end
 
-function N_VMaxNorm_Serial(x::N_Vector)
+N_VDotProd_Serial(x,y) = __N_VDotProd_Serial(convert(N_Vector,x),convert(N_Vector,y))
+
+function __N_VMaxNorm_Serial(x::N_Vector)
     ccall((:N_VMaxNorm_Serial,libsundials_nvecserial),realtype,(N_Vector,),x)
 end
 
-function N_VWrmsNorm_Serial(x::N_Vector,w::N_Vector)
+N_VMaxNorm_Serial(x) = __N_VMaxNorm_Serial(convert(N_Vector,x))
+
+function __N_VWrmsNorm_Serial(x::N_Vector,w::N_Vector)
     ccall((:N_VWrmsNorm_Serial,libsundials_nvecserial),realtype,(N_Vector,N_Vector),x,w)
 end
 
-function N_VWrmsNormMask_Serial(x::N_Vector,w::N_Vector,id::N_Vector)
+N_VWrmsNorm_Serial(x,w) = __N_VWrmsNorm_Serial(convert(N_Vector,x),convert(N_Vector,w))
+
+function __N_VWrmsNormMask_Serial(x::N_Vector,w::N_Vector,id::N_Vector)
     ccall((:N_VWrmsNormMask_Serial,libsundials_nvecserial),realtype,(N_Vector,N_Vector,N_Vector),x,w,id)
 end
 
-function N_VMin_Serial(x::N_Vector)
+N_VWrmsNormMask_Serial(x,w,id) = __N_VWrmsNormMask_Serial(convert(N_Vector,x),convert(N_Vector,w),convert(N_Vector,id))
+
+function __N_VMin_Serial(x::N_Vector)
     ccall((:N_VMin_Serial,libsundials_nvecserial),realtype,(N_Vector,),x)
 end
 
-function N_VWL2Norm_Serial(x::N_Vector,w::N_Vector)
+N_VMin_Serial(x) = __N_VMin_Serial(convert(N_Vector,x))
+
+function __N_VWL2Norm_Serial(x::N_Vector,w::N_Vector)
     ccall((:N_VWL2Norm_Serial,libsundials_nvecserial),realtype,(N_Vector,N_Vector),x,w)
 end
 
-function N_VL1Norm_Serial(x::N_Vector)
+N_VWL2Norm_Serial(x,w) = __N_VWL2Norm_Serial(convert(N_Vector,x),convert(N_Vector,w))
+
+function __N_VL1Norm_Serial(x::N_Vector)
     ccall((:N_VL1Norm_Serial,libsundials_nvecserial),realtype,(N_Vector,),x)
 end
 
-function N_VCompare_Serial(c::realtype,x::N_Vector,z::N_Vector)
+N_VL1Norm_Serial(x) = __N_VL1Norm_Serial(convert(N_Vector,x))
+
+function __N_VCompare_Serial(c::realtype,x::N_Vector,z::N_Vector)
     ccall((:N_VCompare_Serial,libsundials_nvecserial),Void,(realtype,N_Vector,N_Vector),c,x,z)
 end
 
-function N_VInvTest_Serial(x::N_Vector,z::N_Vector)
+N_VCompare_Serial(c,x,z) = __N_VCompare_Serial(c,convert(N_Vector,x),convert(N_Vector,z))
+
+function __N_VInvTest_Serial(x::N_Vector,z::N_Vector)
     ccall((:N_VInvTest_Serial,libsundials_nvecserial),Cint,(N_Vector,N_Vector),x,z)
 end
 
-function N_VConstrMask_Serial(c::N_Vector,x::N_Vector,m::N_Vector)
+N_VInvTest_Serial(x,z) = __N_VInvTest_Serial(convert(N_Vector,x),convert(N_Vector,z))
+
+function __N_VConstrMask_Serial(c::N_Vector,x::N_Vector,m::N_Vector)
     ccall((:N_VConstrMask_Serial,libsundials_nvecserial),Cint,(N_Vector,N_Vector,N_Vector),c,x,m)
 end
 
-function N_VMinQuotient_Serial(num::N_Vector,denom::N_Vector)
+N_VConstrMask_Serial(c,x,m) = __N_VConstrMask_Serial(convert(N_Vector,c),convert(N_Vector,x),convert(N_Vector,m))
+
+function __N_VMinQuotient_Serial(num::N_Vector,denom::N_Vector)
     ccall((:N_VMinQuotient_Serial,libsundials_nvecserial),realtype,(N_Vector,N_Vector),num,denom)
 end
+
+N_VMinQuotient_Serial(num,denom) = __N_VMinQuotient_Serial(convert(N_Vector,num),convert(N_Vector,denom))

src/cvodes.jl

@@ -0,0 +1,66 @@
+"""
+   Wrapper for Sundials `N_Vector` that
+   uses Julia `Vector{realtype}` as the data container.
+
+   Implements `DenseVector` interface and
+   manages automatic destruction of the referenced `N_Vector` when it is
+   no longer in use.
+"""
+immutable NVector <: DenseVector{realtype}
+    ref_nv::Ref{N_Vector}   # reference to N_Vector
+    v::Vector{realtype}     # array that is referenced by N_Vector
+
+    function NVector(v::Vector{realtype})
+        nv = new(Ref{N_Vector}(N_VMake_Serial(length(v), pointer(v))), v)
+        finalizer(nv.ref_nv, release_handle)
+        return nv
+    end
+end
+
+release_handle(ref_nv::Ref{N_Vector}) = N_VDestroy_Serial(ref_nv[])
+
+Base.size(nv::NVector, d...) = size(nv.v, d...)
+Base.stride(nv::NVector, d::Integer) = stride(nv.v, d)
+
+Base.getindex(nv::NVector, i::Real) = getindex(nv.v, i)
+Base.getindex(nv::NVector, i::AbstractArray) = getindex(nv.v, i)
+Base.getindex(nv::NVector, inds...) = getindex(nv.v, inds...)
+
+Base.setindex!(nv::NVector, X, i::Real) = setindex!(nv.v, X, i)
+Base.setindex!(nv::NVector, X, i::AbstractArray) = setindex!(nv.v, X, i)
+Base.setindex!(nv::NVector, X, inds...) = setindex!(nv.v, X, inds...)
+
+##################################################################
+#
+# Methods to convert between Julia Vectors and Sundials N_Vectors.
+#
+##################################################################
+
+Base.convert(::Type{NVector}, v::Vector{realtype}) = NVector(v)
+Base.convert{T<:Real}(::Type{NVector}, v::Vector{T}) = NVector(copy!(similar(v, realtype), v))
+Base.convert(::Type{NVector}, nv::NVector) = nv
+Base.convert(::Type{N_Vector}, nv::NVector) = nv.ref_nv[]
+Base.convert(::Type{Vector{realtype}}, nv::NVector)= nv.v
+Base.convert(::Type{Vector}, nv::NVector)= nv.v
+
+""" `N_Vector(v::Vector{T})`
+
+    Converts Julia `Vector` to `N_Vector`.
+
+    Implicitly creates `NVector` object that manages automatic
+    destruction of `N_Vector` object when no longer in use.
+"""
+Base.convert(::Type{N_Vector}, v::Vector{realtype}) = N_Vector(NVector(v))
+Base.convert{T<:Real}(::Type{N_Vector}, v::Vector{T}) = N_Vector(NVector(v))
+
+nvlength(x::N_Vector) = unsafe_load(unsafe_load(convert(Ptr{Ptr{Clong}}, x)))
+# asarray() creates an array pointing to N_Vector data, but does not take the ownership
+@inline asarray(x::N_Vector) = pointer_to_array(N_VGetArrayPointer_Serial(x), (nvlength(x),), false)
+@inline asarray(x::N_Vector, dims::Tuple) = pointer_to_array(N_VGetArrayPointer_Serial(x), dims, false)
+asarray(x::Vector{realtype}) = x
+asarray(x::Ptr{realtype}, dims::Tuple) = pointer_to_array(x, dims)
+@inline Base.convert(::Type{Vector{realtype}}, x::N_Vector) = asarray(x)
+@inline Base.convert(::Type{Vector}, x::N_Vector) = asarray(x)
+
+nvector(x::Vector{realtype}) = NVector(x)
+#nvector(x::N_Vector) = x