[Python-Dev] Final PEP 311 run

[Tim Peters]

[Mark Hammond]
> I'd like to get PEP311 in for the Python 2.3b1 -
> http://www.python.org/peps/pep-0311.html (or even if I miss, very soon
> after!)

I hope so!  It seems important that the specific projects mentioned in the
PEP test drive this before 2.3 final.

> There appears to be no issues with the technical aspects of the
> PEP (please correct me now if I am wrong).

Some questions occurred while reading the PEP again, primarily are there any
restrictions on which parts of the Python API can be called between an
ensure and its matching release?  For example, is it OK if the thread does a

    Py_BEGIN_ALLOW_THREADS
    whatever
    Py_END_ALLOW_THREADS

pair while an ensure is active in the thread?  Is it OK if the thread does a
nested

    PyAutoThreadState_Ensure()
    whatever
    PyAutoThreadState_Release()

likewise (I'm sure that one is OK, but am not sure the PEP really says so)?
If that is OK, must the nested call use the same PyAutoThreadState_State
handle returned by the outer ensure -- or must it avoid using the same
handle?

> The only issue is the name of the API.

If that's the only issue, check it in yesterday <0.9 wink>.

> To save re-reading the PEP just to understand the names, I will summarize
> here (see the PEP for the full version):
>
> There are 2 new functions, called as a pair.  The first function
> sets up the Python thread state, along with the GIL, so that the current
> thread can safely call the Python API.  The function makes no assumptions
> about the current state of the GIL etc - it works out the current state,
> and does the "right thing".  The second function is the reverse of the
> first, to indicate that the thread has finished with the thread state for
> the time being.
>
> The PEP calls these functions PyAutoThreadState_Ensure() and
> PyAutoThreadState_Release()

I can live with that.

> Reasons for the names in the PEP:
> "Auto" reflects that the current thread-state need not be known
> (whereas the other APIs do).  "Ensure()" reflects that nothing may
> actually be *created* - all we are doing is "ensuring" we have the
> resources, creating only if necessary. On the down-side - "Auto" will
> look strange in the future when this is the standard way of managing
> the lock.  "ThreadState" does not reflect that the function does more
> than manage the PyThreadState - it also manages the locks (which while
> an implementation detail, are currently discrete)

Please put this paragraph of rationale in the docs (leaving out the down
side, and maybe in a footnote)!  Once it's explained, there's nothing
mysterious about the names, and there's no point making future readers guess
at the reasons.

> Other Proposals:
>      Just: PyGIL_Ensure(), PyGIL_Release(): shorter to type, conveys the
> meaning.

Could live with that too.

>      David Abrahams: Prefers SubjectVerbObject, so would prefer
> "PyEnsureGIL" - but likes

Ditto, except grates some against existing naming conventions (generally

    "Py" Subsystem "_" Detail

).

>      PyAcquireInterpreter() and PyReleaseInterpreter() best.

I first read those as having something to do with an interpreter state,
which isn't a good sign.

>      Dropping "Auto" from the PEP gives PyThreadState_Ensure() and
> PyThreadState_Release().

What do you get if you drop the Thread <wink>?

> I admit to liking "PyAcquireInterpreter()" best, but it does not match
> the existing API structure.

PyInterpreter_{Acquire,Release} would, though.

> For the sake of typing, I would be happy to go with Just's
> PyGIL_Ensure(), but maybe PyInterpreter_Ensure() is a good
> compromise.
>
> Other opinions or pronouncements welcome :)

Flip a coin, check it in, have a smoke, don't look back.  I'll join you.