Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

bpo-31884 subprocess set priority on windows #4150

Merged
merged 17 commits into from
Nov 8, 2017
Merged

bpo-31884 subprocess set priority on windows #4150

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
22206b9
add constants for setting process priority
JamesGKent Oct 27, 2017
788a086
Update subprocess.py
JamesGKent Oct 27, 2017
f47ce08
Merge pull request #1 from JamesGKent/subprocess-priority-windows-1
JamesGKent Oct 27, 2017
a7e78e4
Merge pull request #2 from JamesGKent/subprocess-priority-windows
JamesGKent Oct 27, 2017
0b3e805
Create 2017-10-27.bpo-31884.bjhre9.rst
JamesGKent Oct 27, 2017
bdaf817
added constants
JamesGKent Oct 30, 2017
f972658
added constants
JamesGKent Oct 30, 2017
55ace15
fixed missing import
JamesGKent Nov 7, 2017
13f0893
Update subprocess.rst
JamesGKent Nov 7, 2017
382f890
Update subprocess.rst
JamesGKent Nov 7, 2017
197861f
Update subprocess.rst
JamesGKent Nov 7, 2017
2ccf787
Update subprocess.rst
JamesGKent Nov 7, 2017
680efd7
Update subprocess.rst
JamesGKent Nov 7, 2017
5114f8c
Update subprocess.rst
JamesGKent Nov 7, 2017
8d3fac6
Update subprocess.rst
JamesGKent Nov 8, 2017
264fb12
Update subprocess.rst
JamesGKent Nov 8, 2017
0765c90
fixed underline too short
JamesGKent Nov 8, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 86 additions & 5 deletions Doc/library/subprocess.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -516,8 +516,20 @@ functions.

If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
passed to the underlying ``CreateProcess`` function.
*creationflags*, if given, can be :data:`CREATE_NEW_CONSOLE` or
:data:`CREATE_NEW_PROCESS_GROUP`. (Windows only)
*creationflags*, if given, can be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change seems unrelated and I preferred the previous formatting.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'm not sure how this is unrelated? this shows where the added constants should be used?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, when I wrote my comment, the doc was formatted differently.

Ok, now I suggest to format these constants as a list:

* a
* b
* c
* ...

(correctly indented for the current section)

Try to build the documentation to see how it's rendered in HTML. On Unix, it's "make -C Doc html". I don't know how to build it on Windows :-(

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unfortunately i don't currently have access to a unix box (windows 10 broke my dual boot) and currently on a work pc so don't even have git client, doing this through the web interface... so i can't build the docs to see how they look

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

creationflags, if given, can be

I checked in MSDN: in fact, you can specify multiple flags at once:
https://msdn.microsoft.com/en-us/library/windows/desktop/ms686331(v=vs.85).aspx

dwFlags: "A bitfield that determines whether certain STARTUPINFO members are used when the process creates a window. This member can be one or more of the following values."

By the way, please add a column after "can be" ("can be:"), and an empty line after.

I propose: "can be one or more of the following flags:".

:data:`CREATE_NEW_CONSOLE`
:data:`CREATE_NEW_PROCESS_GROUP`
:data:`ABOVE_NORMAL_PRIORITY_CLASS`
:data:`BELOW_NORMAL_PRIORITY_CLASS`
:data:`HIGH_PRIORITY_CLASS`
:data:`IDLE_PRIORITY_CLASS`
:data:`NORMAL_PRIORITY_CLASS`
:data:`REALTIME_PRIORITY_CLASS`
:data:`CREATE_NO_WINDOW`
:data:`DETACHED_PROCESS`
:data:`CREATE_DEFAULT_ERROR_MODE`
:data:`CREATE_BREAKAWAY_FROM_JOB`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about this "versioadded" section. I suggest to remove it.


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A single empty line is enough at the end of this list.


Popen objects are supported as context managers via the :keyword:`with` statement:
on exit, standard file descriptors are closed, and the process is waited for.
Expand Down Expand Up @@ -839,18 +851,87 @@ The :mod:`subprocess` module exposes the following constants.
additional information.

.. data:: CREATE_NEW_CONSOLE

The new process has a new console, instead of inheriting its parent's
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The title of the current section is " Constants". I checked: all constants documented here as specific to Windows. I propose to rename the section to "Windows Constants". Can you please do that?

console (the default).

.. data:: CREATE_NEW_PROCESS_GROUP


.. versionadded:: 3.7
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change seems wrong: this constant was already available on Python 3.6.

A :class:`Popen` ``creationflags`` parameter to specify that a new process
group will be created. This flag is necessary for using :func:`os.kill`
on the subprocess.

This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified.


.. data:: ABOVE_NORMAL_PRIORITY_CLASS

.. versionadded:: 3.7
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The versionadded markup is usually added after the text, and surrounded by an empty line (above and after).

A :class:`Popen` ``creationflags`` parameter to specify that a new process
will have an above average priority.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You have to add ".. versionadded:: 3.7" here: same for each added constant below.


.. data:: BELOW_NORMAL_PRIORITY_CLASS

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
will have a below average priority.

.. data:: HIGH_PRIORITY_CLASS

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
will have a high priority.

.. data:: IDLE_PRIORITY_CLASS

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
will have an idle (lowest) priority.

.. data:: NORMAL_PRIORITY_CLASS

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
will have an normal priority. (default)

.. data:: REALTIME_PRIORITY_CLASS

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
will have realtime priority.
You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts
system threads that manage mouse input, keyboard input, and background disk
flushing. This class can be appropriate for applications that "talk" directly
to hardware or that perform brief tasks that should have limited interruptions.

.. data:: CREATE_NO_WINDOW

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
will not create a window

.. data:: DETACHED_PROCESS

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
will not inherit its parent's console.
This value cannot be used with CREATE_NEW_CONSOLE.

.. data:: CREATE_DEFAULT_ERROR_MODE

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
does not inherit the error mode of the calling process. Instead, the new
process gets the default error mode.
This feature is particularly useful for multithreaded shell applications
that run with hard errors disabled.

.. data:: CREATE_BREAKAWAY_FROM_JOB

.. versionadded:: 3.7
A :class:`Popen` ``creationflags`` parameter to specify that a new process
is not associated with the job.

.. _call-function-trio:

Older high-level API
Expand Down
14 changes: 12 additions & 2 deletions Lib/subprocess.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,13 +164,23 @@ def __init__(self, *, dwFlags=0, hStdInput=None, hStdOutput=None,
from _winapi import (CREATE_NEW_CONSOLE, CREATE_NEW_PROCESS_GROUP,
STD_INPUT_HANDLE, STD_OUTPUT_HANDLE,
STD_ERROR_HANDLE, SW_HIDE,
STARTF_USESTDHANDLES, STARTF_USESHOWWINDOW)
STARTF_USESTDHANDLES, STARTF_USESHOWWINDOW,
ABOVE_NORMAL_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS,
HIGH_PRIORITY_CLASS, IDLE_PRIORITY_CLASS,
NORMAL_PRIORITY_CLASS, REALTIME_PRIORITY_CLASS,
CREATE_NO_WINDOW, DETACHED_PROCESS,
CREATE_DEFAULT_ERROR_MODE, CREATE_BREAKAWAY_FROM_JOB)

__all__.extend(["CREATE_NEW_CONSOLE", "CREATE_NEW_PROCESS_GROUP",
"STD_INPUT_HANDLE", "STD_OUTPUT_HANDLE",
"STD_ERROR_HANDLE", "SW_HIDE",
"STARTF_USESTDHANDLES", "STARTF_USESHOWWINDOW",
"STARTUPINFO"])
"STARTUPINFO",
"ABOVE_NORMAL_PRIORITY_CLASS", "BELOW_NORMAL_PRIORITY_CLASS",
"HIGH_PRIORITY_CLASS", "IDLE_PRIORITY_CLASS",
"NORMAL_PRIORITY_CLASS", "REALTIME_PRIORITY_CLASS",
"CREATE_NO_WINDOW", "DETACHED_PROCESS",
"CREATE_DEFAULT_ERROR_MODE", "CREATE_BREAKAWAY_FROM_JOB"])

class Handle(int):
closed = False
Expand Down
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/Library/2017-10-27.bpo-31884.bjhre9.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
added required constants to subprocess module for setting priotity on windows
12 changes: 12 additions & 0 deletions Modules/_winapi.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1595,6 +1595,18 @@ PyInit__winapi(void)
WINAPI_CONSTANT(F_DWORD, WAIT_OBJECT_0);
WINAPI_CONSTANT(F_DWORD, WAIT_ABANDONED_0);
WINAPI_CONSTANT(F_DWORD, WAIT_TIMEOUT);

WINAPI_CONSTANT(F_DWORD, ABOVE_NORMAL_PRIORITY_CLASS);
WINAPI_CONSTANT(F_DWORD, BELOW_NORMAL_PRIORITY_CLASS);
WINAPI_CONSTANT(F_DWORD, HIGH_PRIORITY_CLASS);
WINAPI_CONSTANT(F_DWORD, IDLE_PRIORITY_CLASS);
WINAPI_CONSTANT(F_DWORD, NORMAL_PRIORITY_CLASS);
WINAPI_CONSTANT(F_DWORD, REALTIME_PRIORITY_CLASS);

WINAPI_CONSTANT(F_DWORD, CREATE_NO_WINDOW);
WINAPI_CONSTANT(F_DWORD, DETACHED_PROCESS);
WINAPI_CONSTANT(F_DWORD, CREATE_DEFAULT_ERROR_MODE);
WINAPI_CONSTANT(F_DWORD, CREATE_BREAKAWAY_FROM_JOB);

WINAPI_CONSTANT("i", NULL);

Expand Down