Comments

Author: Wimmerer

src/SuiteSparseGraphBLAS.jl

@@ -94,6 +94,7 @@ include("options.jl")
 include("misc.jl")
 export libgb
 export UnaryOps, BinaryOps, Monoids, Semirings, SelectOps, Descriptors #Submodules
+export UnaryOp, BinaryOp, Monoid, Semiring #UDFs
 export Descriptor #Types
 export xtype, ytype, ztype
 export GBScalar, GBVector, GBMatrix #arrays

src/operators/binaryops.jl

@@ -68,22 +68,22 @@ function _createbinaryops()
 end
 
 function BinaryOp(name)
-    if isGxB(name) || isGrB(name)
+    if isGxB(name) || isGrB(name) #If it's a built-in drop the prefix
         simplifiedname = name[5:end]
     else
         simplifiedname = name
     end
     containername = Symbol(simplifiedname, "_T")
     exportedname = Symbol(simplifiedname)
-    if isGxB(name) || isGrB(name)
+    if isGxB(name) || isGrB(name) #Built-in is immutable, no finalizer
         structquote = quote
             struct $containername <: AbstractBinaryOp
                 pointers::Dict{DataType, libgb.GrB_BinaryOp}
                 name::String
                 $containername() = new(Dict{DataType, libgb.GrB_BinaryOp}(), $name)
             end
         end
-    else
+    else #UDF is mutable for finalizer
         structquote = quote
             mutable struct $containername <: AbstractBinaryOp
                 pointers::Dict{DataType, libgb.GrB_BinaryOp}
@@ -101,16 +101,17 @@ function BinaryOp(name)
             end
         end
     end
-    @eval(Types, $structquote)
+    @eval(Types, $structquote) #eval container *type* into Types submodule
     constquote = quote
         const $exportedname = Types.$containername()
         export $exportedname
     end
-    @eval(BinaryOps, $constquote)
+    @eval(BinaryOps, $constquote) #eval actual op into BinaryOps submodule
     return getproperty(BinaryOps, exportedname)
 end
 
 #This is adapted from the fork by cvdlab.
+#Add a new GrB_BinaryOp to an AbstractBinaryOp
 function _addbinaryop(
     op::AbstractBinaryOp,
     fn::Function,
@@ -130,14 +131,21 @@ function _addbinaryop(
     return nothing
 end
 
+#BinaryOp constructors
+######################
+
 function BinaryOp(name::String, fn::Function, ztype, xtype, ytype)
     op = BinaryOp(name)
     _addbinaryop(op, fn, toGBType(ztype), toGBType(xtype), toGBType(ytype))
     return op
 end
+
+#xtype == ytype == ztype
 function BinaryOp(name::String, fn::Function, type::DataType)
     return BinaryOp(name, fn, type, type, type)
 end
+
+#Vectors of _type, add one function for each triple.
 function BinaryOp(
     name::String,
     fn::Function,
@@ -153,9 +161,13 @@ function BinaryOp(
     end
     return op
 end
+
+#Vector of type, xtype == ytype == ztype
 function BinaryOp(name::String, fn::Function, type::Vector{DataType})
     return BinaryOp(name, fn, type, type, type)
 end
+
+#Use the built-in primitives.
 function BinaryOp(name::String, fn::Function)
     return BinaryOp(name, fn, valid_vec)
 end

src/operators/monoids.jl

@@ -36,17 +36,18 @@ function _createmonoids()
         Monoid(name)
     end
 end
+
 function Monoid(name)
     containername, exportedname = _monoidnames(name)
-    if isGxB(name) || isGrB(name)
+    if isGxB(name) || isGrB(name) #Built-ins are immutable
         structquote = quote
             struct $containername <: AbstractMonoid
                 pointers::Dict{DataType, libgb.GrB_Monoid}
                 name::String
                 $containername() = new(Dict{DataType, libgb.GrB_Monoid}(), $name)
             end
         end
-    else
+    else #UDFs are mutable for finalizing
         structquote = quote
             mutable struct $containername <: AbstractMonoid
                 pointers::Dict{DataType, libgb.GrB_Monoid}
@@ -74,6 +75,7 @@ function Monoid(name)
 end
 
 #This is adapted from the fork by cvdlab
+#NOTE: Terminals do not work with built in BinaryOps.
 function _addmonoid(op::AbstractMonoid, binop::BinaryUnion, id::T, terminal = nothing) where {T}
     if terminal === nothing
         terminal = C_NULL
@@ -96,8 +98,12 @@ function _addmonoid(op::AbstractMonoid, binop::BinaryUnion, id::T, terminal = no
     op.pointers[T] = monref[]
     return nothing
 end
+
+#Monoid Constructors
+####################
+
 function Monoid(name::String, binop::BinaryUnion, id::T, terminal = nothing) where {T}
-    if binop isa AbstractBinaryOp
+    if binop isa AbstractBinaryOp #If this is an AbstractBinaryOp we need to narrow down
         binop = binop[T]
     end
     m = Monoid(name)

src/operators/semirings.jl

@@ -274,19 +274,22 @@ function Semiring(name)
     return getproperty(Semirings, exportedname)
 end
 
+#Add typed ⊕ and ⊗ to semiring
 function _addsemiring(rig::AbstractSemiring, add::libgb.GrB_Monoid, mul::libgb.GrB_BinaryOp)
     rigref = Ref{libgb.GrB_Semiring}()
     libgb.GrB_Semiring_new(rigref, add, mul)
     rig.pointers[xtype(add)] = rigref[]
     return nothing
 end
 
+#New semiring with typed ⊕ and ⊗
 function Semiring(name::String, add::libgb.GrB_Monoid, mul::libgb.GrB_BinaryOp)
     rig = Semiring(name)
     _addsemiring(rig, add, mul)
     return rig
 end
 
+#New semiring with all supported types in the intersection of validtypes(⊕) and validtypes(⊗)
 function Semiring(name::String, add::AbstractMonoid, mul::AbstractBinaryOp)
     tadd = validtypes(add)
     tmul = validtypes(mul)

src/operators/unaryops.jl

@@ -5,13 +5,6 @@ end
 
 const UnaryUnion = Union{AbstractUnaryOp, libgb.GrB_UnaryOp}
 
-function _unarynames(name)
-    simple = splitconstant(name)[2]
-    containername = Symbol(simple, "_UNARY_T")
-    exportedname = Symbol(simple)
-    return containername, exportedname
-end
-
 #TODO: Rewrite
 function _createunaryops()
     builtins = [
@@ -71,13 +64,14 @@ function _createunaryops()
 end
 
 function UnaryOp(name)
-    if isGxB(name) || isGrB(name)
+    if isGxB(name) || isGrB(name) #If it's a GrB/GxB op we don't want the prefix
         simplifiedname = name[5:end]
     else
         simplifiedname = name
     end
     tname = Symbol(simplifiedname * "_T")
     simplifiedname = Symbol(simplifiedname)
+    #If it's a built-in we probably want immutable struct. Need to check original name.
     if isGxB(name) || isGrB(name)
         structquote = quote
             struct $tname <: AbstractUnaryOp
@@ -86,7 +80,7 @@ function UnaryOp(name)
                 $tname() = new(Dict{DataType, libgb.GrB_UnaryOp}(), $name)
             end
         end
-    else
+    else #If it's a UDF we need a mutable for finalizing purposes.
         structquote = quote
             mutable struct $tname <: AbstractUnaryOp
                 pointers::Dict{DataType, libgb.GrB_UnaryOp}
@@ -104,7 +98,7 @@ function UnaryOp(name)
             end
         end
     end
-    @eval(Types, $structquote)
+    @eval(Types, $structquote) #Eval the struct into the Types submodule to avoid clutter.
     constquote = quote
         const $simplifiedname = Types.$tname()
         export $simplifiedname
@@ -114,8 +108,8 @@ function UnaryOp(name)
 end
 
 #This is adapted from the fork by cvdlab.
+#Add a new GrB_UnaryOp to an AbstractUnaryOp.
 function _addunaryop(op::AbstractUnaryOp, fn::Function, ztype::GBType{T}, xtype::GBType{U}) where {T, U}
-
     function unaryopfn(z, x)
         unsafe_store!(z, fn(x))
         return nothing
@@ -127,14 +121,18 @@ function _addunaryop(op::AbstractUnaryOp, fn::Function, ztype::GBType{T}, xtype:
     return nothing
 end
 
+#UnaryOp constructors
+#####################
 function UnaryOp(name::String, fn::Function, ztype, xtype)
     op = UnaryOp(name)
     _addunaryop(op, fn, toGBType(ztype), toGBType(xtype))
     return op
 end
+#Same xtype, ztype.
 function UnaryOp(name::String, fn::Function, type)
     return UnaryOp(name, fn, type, type)
 end
+#Vector of xtypes and ztypes, add a GrB_UnaryOp for each.
 function UnaryOp(name::String, fn::Function, ztype::Vector{DataType}, xtype::Vector{DataType})
     op = UnaryOp(name)
     length(ztype) == length(xtype) || error("Lengths of ztype and xtype must match.")
@@ -143,9 +141,11 @@ function UnaryOp(name::String, fn::Function, ztype::Vector{DataType}, xtype::Vec
     end
     return op
 end
+#Vector but same ztype xtype.
 function UnaryOp(name::String, fn::Function, type::Vector{DataType})
     return UnaryOp(name, fn, type, type)
 end
+#Construct it using the built in primitives.
 function UnaryOp(name::String, fn::Function)
     return UnaryOp(name, fn, valid_vec)
 end