Improve documentation related to JL_GC_PUSH*

[ronisbr]

Hi guys,

I had some problems related to embedding Julia in C/C++ software. I posted some topics in Discourse and, finally, I managed to make it work. This PR tries to improve the documentation based on my experience and some advices I found on old Discourse posts. Please, help me to review this, because I am not entirely sure that everything is correct.

[ronisbr]

Hi @yuyichao

Thanks for the review! I have modified the commit according to your suggestions. Please, see if everything is OK now.

[ronisbr]

Done @yuyichao ! I think added all your advices to the PR now. Please, see if everything seems right. Thanks for the review again!

[ronisbr]

@yuyichao done!

[ronisbr]

Btw @yuyichao , is there an easy way to create the RefValue from C then this one:

    jl_value_t* var       = jl_eval_string("sqrt(2.0)");
    jl_datatype_t* reft   = (jl_datatype_t*)jl_eval_string("Base.RefValue{Float64}");
    jl_value_t* rvar      = jl_new_struct(reft, var);

I am thinking to put the example when you have to wrap around a RefValue to make things clear to the user.

[yuyichao]

Errr.......... So a few problems,

1. Is there an easy way to create the RefValue{Float64} from C

   That's about as easy as it gets. You can cache the type though so you don't need to eval that every time. Also note that you must root the var before calling any other functions in that code.

2. Even with the local root fixed, that code does not protect var from being freed. I said many times that you want RefValue{Any} (or type with equivalent layout), not RefValue{Float64}. You want to store the pointer, not the object.

[ronisbr]

@yuyichao yes, I understood. This was just a little example to see the easiest way to create a RefValue. The code I suppose it will work to store the pointer in the IdDict and avoid deallocation is:

    jl_value_t* var = jl_eval_string("sqrt(2.0)");
    JL_GC_PUSH1(&var);
    jl_datatype_t* reft = (jl_datatype_t*)jl_eval_string("Base.RefValue{Any}");
    jl_value_t* rvar = jl_new_struct(reft, &var);
    JL_GC_POP();

    jl_function_t* setindex = jl_get_function(jl_base_module, "setindex!");
    jl_value_t* refs = jl_eval_string("refs = IdDict()");
    jl_call3(setindex, refs, rvar, rvar);

Is it correct?

[yuyichao]

This was just a little example to see the easiest way to create a RefValue

Well, that's fine, as long as you don't

put the example when you have to wrap around a RefValue to make things clear to the user.

Putting this example here will definitely not make it more clear to the user.

jl_value_t* rvar = jl_new_struct(reft, &var);

jl_new_struct(reft, var)

    jl_function_t* setindex = jl_get_function(jl_base_module, "setindex!");
    jl_value_t* refs = jl_eval_string("refs = IdDict()");
    jl_call3(setindex, refs, rvar, rvar);

And given that you've asked about jl_set_global(jl_main_module, jl_symbol("var"), var);, I would definitely make it clcear that, setindex, refs (and also reft) should only be created during initialization and not on each invocation of the function.

[ronisbr]

Fair enough! Sorry about the confusion, I will not put that first code in PR. I will add this and submit for your review. Thank you very much for your time 👍

[ronisbr]

Done @yuyichao , hope I got everything right this time!

[yuyichao]

LGTM. Would be good to also explain why rather than how. though that's not something I am very good at doing either.

[ronisbr]

Hi @yuyichao,

I can try to dig the information and submit another PR more explanation about what is going on under the hood! Can you please point me to where should I look for the information to understand what’s going on ? I confess that I am very new in this area (embedding Julia in C), but I have a lot of interest given future projects I envision in my institute.

[c42f]

Would be good to also explain why rather than how

Here's a great article on documentation which shows quite clearly (IMO) that these are two complimentary things, and each quite important in their own ways: https://www.divio.com/blog/documentation/

Highly recommended as a great tool for clarifying what needs to be written in a given piece of documentation.

[ronisbr]

Hi guys,

Should I do anything more here?

[c42f]

This looks good to me. I made a couple of grammatical fixes and some minor edits to make sure it fits into the surrounding documentation.

[c42f]

Travis failures are unrelated so I'm merging this. (Linux failures are #27788; OSX failure is a single failure in SharedArrays.)

[c42f]

I've squashed the changes and pushed that to master manually. I did this on the command line to preserve the authorship info; it's frustrating but it seems github will overwrite the author if you click the "Squash+merge" button.

This has also confused the github UI a bit, but don't worry, it's in master. Perhaps the right thing is to squash on the command line, force push to the PR branch, and then click the rebase+merge button. I don't know why preserving authorship via the UI is so hard for github to get right :-( Anyone who knows better how to deal with squashing multi-author changes, please let me know!