gh-85222: Document the side effect in multiprocessing #136426
Conversation
bedevere-app
bot
added
awaiting review
docs
| @@ -867,6 +867,10 @@ For an example of the usage of queues for interprocess communication see | |||
| locks/semaphores. When a process first puts an item on the queue a feeder | |||
| thread is started which transfers objects from a buffer into the pipe. | |||
|
|
|||
| If the global start method has not been set, calling this function will | |||
| have the side effect of setting the current global start method. | |||
| See the :func:`get_context` function. | |||
There was a problem hiding this comment.
I think repeating the same words here may be a bit 'noisy'. Could we just mention it once?
There was a problem hiding this comment.
My concern is that if a user only uses one of these functions and checks that function's documentation, and unfortunately that is not the function that contains this document, they may mess it up.
But I'm unsure about this.
There was a problem hiding this comment.
I may be biased but I don't think the extra clarity hurts... I'm with @aisk
There was a problem hiding this comment.
yeah, I asked for this to be mentioned everywhere for that reason as this is non-obvious behavior of multiprocessing. This could probably be refined a bit, i'll point some docs focused reviewers at it.
There was a problem hiding this comment.
sorry i just had to :)
There was a problem hiding this comment.
My concern is that if a user only uses one of these functions and checks that function's documentation, and unfortunately that is not the function that contains this document, they may mess it up.
But I'm unsure about this.
IMO it may be better if we mentioned it once and create a reference link to the mention in every function. I'm not sure too (｡･ω･｡)
There was a problem hiding this comment.
The repeated part could be a single sentence like Ensures that the current global start method is set., with ”global start method” linking to a longer explanation in a dedicated section.
|
|
||
| .. function:: Value(typecode_or_type, *args, lock=True) | ||
| Note that *lock* and *ctx* are keyword-only argument. |
There was a problem hiding this comment.
They are parameters, not arguments.
| calling this function will have the side effect of setting the current global | ||
| start method if it has not been set already. See the :func:`get_context` | ||
| function. | ||
|
|
There was a problem hiding this comment.
Same here, parameters, not arguments.
| @@ -977,6 +981,10 @@ For an example of the usage of queues for interprocess communication see | |||
|
|
|||
| It is a simplified :class:`Queue` type, very close to a locked :class:`Pipe`. | |||
|
|
|||
| If the global start method has not been set, calling this function will | |||
There was a problem hiding this comment.
After there's final wording for the repeated part is reworded, check that it's in all the contexts.
(This is class documentation; it should be “creating a SimpleQueue object” rather than “calling this function”.)
📚 Documentation preview 📚: https://cpython-previews--136426.org.readthedocs.build/