multiprocessing.Semaphore has undocumented get_value() method

[23982c60-ed6c-47d1-96c2-69d417bd81b3]

BPO	40797
Nosy	@pitrou, @applio, @remilapeyre

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['type-bug', 'library', '3.10'] title = 'multiprocessing.Semaphore has undocumented get_value() method' updated_at = user = 'https://github.com/remilapeyre' ``` bugs.python.org fields: ```python activity = actor = 'ned.deily' assignee = 'none' closed = False closed_date = None closer = None components = ['Library (Lib)'] creation = creator = 'remi.lapeyre' dependencies = [] files = [] hgrepos = [] issue_num = 40797 keywords = [] message_count = 1.0 messages = ['370128'] nosy_count = 3.0 nosy_names = ['pitrou', 'davin', 'remi.lapeyre'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = 'behavior' url = 'https://bugs.python.org/issue40797' versions = ['Python 3.10'] ```

[23982c60-ed6c-47d1-96c2-69d417bd81b3]

The threading.Semaphore class does not have this method, it is undocumented and useless on some system (at least MacOS):

>>> s.get_value()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/multiprocessing/synchronize.py", line 129, in get_value
    return self._semlock._get_value()
NotImplementedError

The implementation is at https://github.com/python/cpython/blob/master/Modules/_multiprocessing/semaphore.c#L537-L553

I think this method could be removed, since it's undocumented and probably not used can I just remove it or does it need a deprecation cycle?

[gst]

why could not the method be simply documented ?

I'm using it already :)

[platobms]

I concur with @gst . Was this never intended to be officially supported or was it just implemented only for certain systems (and thus not yet documented)?

It appears to not function on macOS (not implemented) but does work on Linux (x86/Python3.8 and ARM64/Python3.6).

[gst]

given it's a public method and has been present for long (always?) and has a well defined and valuable purpose : it should be documented IMHO.

[pitrou]

If you manage to make it work cross-platform and make sure tests are present for it, then we could probably document it officially as well.

[platobms]

Thanks, makes sense to add tests before promoting it officially.

Regarding cross-platform support, is there a reason that the method can't just apply for OSes which support the necessary underlying C functions? For example (and understandably) different start methods are supported with a comment in the documentation: "Available on POSIX platforms which support passing file descriptors over Unix pipes such as Linux."

[pitrou]

Regarding cross-platform support, is there a reason that the method can't just apply for OSes which support the necessary underlying C functions?

We could do that as well. However, it would make sense to first check if support can be added for the missing platforms.

[gst]

If you manage to make it work cross-platform

So you only speak about MacOS, right ?

but MacOS has simply not implemented the function (or yes: they return -1 thus) if I've seen correctly. In that case we would need to either : use something else than regular semaphore for this OS. or else: maintain the count ourself (also limited to this case/OS) (but that would require a (preferably) dedicated Lock with each Semaphore).

I remind sem_getvalue is POSIX after all :)