Base.@ccallable blows chunks

General Usage
1

Not much documentation out there I have found to help me with this. Do we not allow setting of references in the @ccallable function? I’ve had this problem with every function I tried to define as @ccallable for use in a C-library with PackageCompiler. This is my first time attempting to use PacakgeCompiler.

The code:

const inputRef=Ref{julia_input_data}(julia_input_data())
const isCalculationValid=Ref{Bool}(false)

Base.@ccallable function julia_reset_inputRef()::Cint
    inputRef[]=julia_input_data()
    isCalculationValid[]=false
    return Cint(0)
end

The output (sanitized)

ERROR: LoadError: cannot document the following expression:
#= c:\mydir\mypackage\src\mypac_ccall_interface.jl:87 =# 
Base.@ccallable function julia_reset_inputRef()::Cint
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:87 =#
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:88 =#
        inputRef[] = julia_input_data()
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:89 =#
        isCalculationValid[] = false
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:90 =#
        return Cint(0)
    end

'Base.var"@ccallable"' not documentable. See 'Bas
2

That error usually shows up when you try to attach a docstring to a macro call that returns a compound expression but lacks Base.@__doc__ marking which subexpressions the docstring is attached to, see here. If you @macroexpand the @ccallable expression you can see it’s a compound expression. It’s strange because your code doesn’t have docstrings at all.

3

That’s because I didn’t give you that part. :slight_smile:

"The julia_reset_inputs will disassociate the previous mutable structure reference with the inputRef pointer and create a new julia_input_data object to be referenced."
function julia_reset_inputRef()::Cint
    inputRef[]=julia_input_data()
    isCalculationValid[]=false
    return Cint(0)
end

So you are saying that I can’t have a docstring attached to any function that uses Base.@ccallable?

4

I think you may be a genius. Any way to properly document C-library designated functions?

5

Honestly, that sounds like a bug with the docs system. Could you file an issue?

6

How about assigning the docstring to a free function.

"The julia_reset_inputs will disassociate the previous mutable structure reference with the inputRef pointer and create a new julia_input_data object to be referenced."
julia_reset_inputRef


Base.@ccallable function julia_reset_inputRef()::Cint
   # ...
end
2 Likes
7

If I can remember my github account login I will. :slight_smile:

1 Like
8

Done.

1 Like
9

Fix proposed in fix #51586, annotate method from `@ccallable` with `@__doc__` by mbauman · Pull Request #51587 · JuliaLang/julia · GitHub.

1 Like
10

I think this is the only way.

In general there’s no guarantee that you can put a docstring above a macro call transforming an input expression and expect the input expression to be documented; if the output expression is compound, the macro must manually specify which subexpression gets the docstring. If it doesn’t do that, one workaround is to attach the docstring to the input expression in a begin block as an input for the macro, hoping the macro is able to handle it. @ccallable requires the input to be a function block so it can’t. Base.@__doc__ helps remove the need for macros to tiptoe around or dive into such begin blocks.

julia> Base.@ccallable begin
       "The julia_reset_inputs will disassociate the previous mutable structure reference with the inputRef pointer and create a new julia_input_data object to be referenced."
       function julia_reset_inputRef()::Cint
           inputRef[]=julia_input_data()
           isCalculationValid[]=false
           return Cint(0)
       end
       end
ERROR: LoadError: expected method definition in @ccallable
Stacktrace:
 [1] error(s::String)
   @ Base ./error.jl:35
 [2] expand_ccallable(rt::Nothing, def::Expr)
   @ Base ./c.jl:548
 [3] var"@ccallable"(__source__::LineNumberNode, __module__::Module, def::Any)
   @ Base ./c.jl:558