Some more docs

[mejrs]

• Use the new is method in some doc examples.
• Clarifies some safety docs

[mejrs]

I've taken a liking to properly naming lifetimes as of recently. What would you think of renaming the Python<'py> lifetime to Python<'gil>? It's still short and I think it represents the meaning of the lifetime better.

[adamreichold]

I agree with the sentiment, but I am not sure if the improvement is worth the churn?

[davidhewitt]

It should be a fairly mechanical change if we wanted to update. If we were consistent with always having 'gil for the name of the GIL lifetime when present, that would also help make it clear when things did not depend on the GIL.

[mejrs]

Re: threads, I was thinking about this:

fn foo(py: Python<'_>){
    let handle = std::thread::spawn(|| unsafe {
        let py = Python::assume_gil_acquired();
        // call some pyo3 apis
    });
    
    handle.join().unwrap();
}

Is this legal? Should we declare that it is not allowed?

[adamreichold]

As spawn and join are synchronization points, I think this is legal as long as there is absolutely nothing happening in between spawn and join which could prevent the join from happening, i.e. the thread must be scoped.

However, I would suggest not including this example in the documentation as it opens more questions than it answers IMHO and I think the current wording is the right thing to do in almost all of the cases. When someone has to handle a case where this is not so (as in your example), they should be sure enough to figure it out. Everybody else is probably just confused by watering down the statement about the current thread.

[mejrs]

To clarify, the way I worded it would declare that it's not allowed.

[davidhewitt]

I don't think the above is legal - holding the GIL on the Python side also sets a bunch of thread-local variables about the interpreter state. Not holding the GIL in the exact thread the Python API is called in will likely lead to segfaults by reading invalid values from these variables.

[davidhewitt]

Nice improvements, thanks!

Needs formatting fix, else I would have clicked merge ☺️

[davidhewitt]

I don't think the above is legal - holding the GIL on the Python side also sets a bunch of thread-local variables about the interpreter state. Not holding the GIL in the exact thread the Python API is called in will likely lead to segfaults by reading invalid values from these variables.

[davidhewitt]

It should be a fairly mechanical change if we wanted to update. If we were consistent with always having 'gil for the name of the GIL lifetime when present, that would also help make it clear when things did not depend on the GIL.