Skip to content

bpo-31368: Expose preadv (preadv2) and pwritev (pwritev2) in the os module #5239

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

Merged
vstinner merged 14 commits into from
Jan 27, 2018
Merged

bpo-31368: Expose preadv (preadv2) and pwritev (pwritev2) in the os module #5239

Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
ea21128
Expose preadv2 in os module
pablogsal Jan 19, 2018
4570976
Add News entry
pablogsal Jan 19, 2018
21a3004
Add correct guards for the presence of preadv2
pablogsal Jan 19, 2018
8a2a2a3
Implement check for individual constants
pablogsal Jan 19, 2018
c0c53dc
Implemented preadv and join implementation to preadv2
pablogsal Jan 19, 2018
4ddbca9
Clean iov on error
pablogsal Jan 20, 2018
cac62ac
Add documentation in the os module
pablogsal Jan 22, 2018
c7b7285
Add information about the rest of the parameters
pablogsal Jan 22, 2018
58910d0
Expose pwritev and pwritev2 in os module
pablogsal Jan 23, 2018
f7cdf22
Fix style issues and Docs
pablogsal Jan 23, 2018
47f65b5
Correct style, update docs, fix misused API
pablogsal Jan 23, 2018
87c6970
Improve tests, clean names and correct style
pablogsal Jan 26, 2018
cb74d38
Correct documentation
pablogsal Jan 26, 2018
5563b8d
Correct typos, docstring and improve Docs
pablogsal Jan 27, 2018
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
Prev Previous commit
Next Next commit
Correct documentation
  • Loading branch information
@pablogsal
pablogsal committed Jan 26, 2018
commit cb74d38bb0f4ff1a9e28279afeca908d92cf0634
22 changes: 11 additions & 11 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1104,10 +1104,10 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: pwritev(fd, buffers, offset, flags=0)

Combines the functionality of :func:`os.writev` and :func:`os.pwrite`. It
writes the contents of *buffers* to file descriptor *fd*. *buffers* must be
a sequence of :term:`bytes-like objects <bytes-like object>`. Buffers are
processed in array order. Entire contents of first buffer is written before
proceeding to second, and so on. The operating system may set a limit
writes the contents of *buffers* to file descriptor *fd* at offset *offset*.
*buffers* must be a sequence of :term:`bytes-like objects <bytes-like object>`.
Buffers are processed in array order. Entire contents of first buffer is written
before proceeding to second, and so on. The operating system may set a limit
(sysconf() value SC_IOV_MAX) on the number of buffers that can be used.
:func:`~os.pwritev` writes the contents of each object to the file descriptor
and returns the total number of bytes written.
Expand All @@ -1116,18 +1116,18 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
The *flags* argument contains a bitwise OR of zero or more of the following
flags:

- RWF_DSYNC
- RWF_SYNC
- RWF_DSYNC
- RWF_SYNC

:func:`~os.pwritev` will call *pwritev2* system call if available, which modifies
the behavior on a per-call basis based on the value of the *flags* argument. The

@vstinner vstinner Jan 27, 2018

Copy link
Copy Markdown
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 that ", which modifies the behavior on a per-call basis based on the value of the flags argument." is needed. Nobody expects a flag passed to a function to have an effect on following calls. And the usage of pwrite2() doesn't mean that the caller must pass a non-zero flags. This sentence is confusing.

:func:`~os.pwritev2` function is required to pass flags.

@vstinner vstinner Jan 27, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

No, there is no :func:~os.pwritev2 function, stop creating links to it.

I suggested "The C function :func:pwritev2", or you can just write pwrite2().


*pwritev2* and *flags* different than zero are available since Linux version
4.7 and newer.

The :func:`~os.pwritev2` function is required to pass flags.

@vstinner vstinner Jan 26, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

nitpick: I would move this sentence before describing on which Linux platforms version it is available.

@vstinner vstinner Jan 27, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

ditto, don't write ":func:~os.pwritev2 function" but "C :c:func:pwritev2 function" or just pwrite2().

Note the "c" prefix before "func".


*pwritev2* and *flags* different than zero are available since Linux version
4.7.

@vstinner vstinner Jan 27, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

"The :func:~os.pwritev2 function is required to pass flags. pwritev2 and flags different than zero are available since Linux version 4.7."

I'm not sure that the Python has to mention pwritev2(). It's confusing and useless. I don't think that the documentation of other os function lists each internal called C functions.

I suggest something simpler like: "Using non-zero flags requires Linux 4.7 or newer."


Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,
OpenBSD (version 2.7 and newer).

Expand Down Expand Up @@ -1246,7 +1246,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
data into each buffer until it is full and then move on to the next buffer in
the sequence to hold the rest of the data. Its fourth argument, *offset*,
specifies the file offset at which the input operation is to be performed.
:func:`~os.preadv` return the total number of bytes read (which may be less than
:func:`~os.preadv` return the total number of bytes read (which can be less than
the total capacity of all the objects).

The flags argument contains a bitwise OR of zero or more of the following
Expand All @@ -1257,7 +1257,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo

:func:`~os.preadv` will call *preadv2* system call if available, which modifies
the behavior on a per-call basis based on the value of the *flags* argument. The
:func:`~os.preadv2` function is required to pass flags.
:c:func:`preadv2` function is required to pass flags.

*preadv2* and flags different than zero are available since Linux version
4.6 and newer.
Expand Down