multiprocessing.Semaphore has undocumented get_value() method

[remilapeyre]

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:

assignee = None
closed_at = None
created_at = <Date 2020-05-27.20:27:22.034>
labels = ['type-bug', 'library', '3.10']
title = 'multiprocessing.Semaphore has undocumented get_value() method'
updated_at = <Date 2020-05-27.23:09:48.701>
user = 'https://github.com/remilapeyre'

bugs.python.org fields:

activity = <Date 2020-05-27.23:09:48.701>
actor = 'ned.deily'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2020-05-27.20:27:22.034>
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']

[remilapeyre]

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 :)