cfunction: add help for struct CFunction (#27506)

This struct had a brief mention in the manual,
but was missing NEWs and info about usage

fix #27490

NEWS.md

@@ -996,8 +996,11 @@ Deprecated or removed
 
   * `Base.SparseArrays.SpDiagIterator` has been removed ([#23261]).
 
-  * The tuple-of-types form of `cfunction`, `cfunction(f, returntype, (types...))`, has been deprecated
-    in favor of the tuple-type form `cfunction(f, returntype, Tuple{types...})` ([#23066]).
+  * The function `cfunction`, has been deprecated in favor of a macro form `@cfunction`.
+    Most existing uses can be upgraded simply by adding a `@`.
+    The new syntax now additionally supports allocating closures at runtime,
+    for dealing with C APIs that don't provide a separate `void* env`-type callback
+    argument. ([#26486])
 
   * `diagm(v::AbstractVector, k::Integer=0)` has been deprecated in favor of
     `diagm(k => v)` ([#24047]).

base/c.jl

@@ -16,12 +16,22 @@ respectively.
 """
 cglobal
 
-struct CFunction
+"""
+    CFunction struct
+
+Garbage-collection handle for the return value from `@cfunction`
+when the first argument is annotated with '\$'.
+Like all `cfunction` handles, it should be passed to `ccall` as a `Ptr{Cvoid}`,
+and will be converted automatically at the call site to the appropriate type.
+
+See [`@cfunction`](@ref).
+"""
+struct CFunction <: Ref{Cvoid}
     ptr::Ptr{Cvoid}
     f::Any
     _1::Ptr{Cvoid}
     _2::Ptr{Cvoid}
-    let construtor = false end
+    let constructor = false end
 end
 unsafe_convert(::Type{Ptr{Cvoid}}, cf::CFunction) = cf.ptr
 
@@ -31,11 +41,12 @@ unsafe_convert(::Type{Ptr{Cvoid}}, cf::CFunction) = cf.ptr
 
 Generate a C-callable function pointer from the Julia function `closure`
 for the given type signature.
+To pass the return value to a `ccall`, use the argument type `Ptr{Cvoid}` in the signature.
 
 Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression
 (although it can include a splat expression). And that these arguments will be evaluated in global scope
 during compile-time (not deferred until runtime).
-Adding a `\$` in front of the function argument changes this to instead create a runtime closure
+Adding a '\$' in front of the function argument changes this to instead create a runtime closure
 over the local variable `callable`.
 
 See [manual section on ccall and cfunction usage](@ref Calling-C-and-Fortran-Code).

base/compiler/validation.jl

@@ -22,7 +22,7 @@ const VALID_EXPR_HEADS = IdDict{Any,Any}(
     :meta => 0:typemax(Int),
     :global => 1:1,
     :foreigncall => 3:typemax(Int),
-    :cfunction => 6:6,
+    :cfunction => 5:5,
     :isdefined => 1:1,
     :simdloop => 0:0,
     :gc_preserve_begin => 0:typemax(Int),

doc/src/base/c.md

@@ -4,6 +4,7 @@
 ccall
 Core.Intrinsics.cglobal
 Base.@cfunction
+Base.CFunction
 Base.unsafe_convert
 Base.cconvert
 Base.unsafe_load