From edf5132dfe43ee94aaabe84163fc4aca825903a8 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Thu, 24 Feb 2011 03:03:46 +0000 Subject: [PATCH] Merged revisions 88540-88541 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r88540 | benjamin.peterson | 2011-02-23 20:46:00 -0600 (Wed, 23 Feb 2011) | 1 line this seems to be pointlessly nested ........ r88541 | benjamin.peterson | 2011-02-23 20:53:05 -0600 (Wed, 23 Feb 2011) | 1 line rewrite ........ --- Doc/library/io.rst | 66 ++++++++++++++++++++++------------------------ 1 file changed, 31 insertions(+), 35 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 26ddd8f22d..0584b70a1b 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -785,37 +785,33 @@ Text I/O inherits :class:`codecs.IncrementalDecoder`. -Advanced topics ---------------- - -Here we will discuss several advanced topics pertaining to the concrete -I/O implementations described above. - Performance -^^^^^^^^^^^ +----------- + +This section discusses the performance of the provided concrete I/O +implementations. Binary I/O -"""""""""" - -By reading and writing only large chunks of data even when the user asks -for a single byte, buffered I/O is designed to hide any inefficiency in -calling and executing the operating system's unbuffered I/O routines. The -gain will vary very much depending on the OS and the kind of I/O which is -performed (for example, on some contemporary OSes such as Linux, unbuffered -disk I/O can be as fast as buffered I/O). The bottom line, however, is -that buffered I/O will offer you predictable performance regardless of the -platform and the backing device. Therefore, it is most always preferable to -use buffered I/O rather than unbuffered I/O. +^^^^^^^^^^ + +By reading and writing only large chunks of data even when the user asks for a +single byte, buffered I/O hides any inefficiency in calling and executing the +operating system's unbuffered I/O routines. The gain depends on the OS and the +kind of I/O which is performed. For example, on some modern OSes such as Linux, +unbuffered disk I/O can be as fast as buffered I/O. The bottom line, however, +is that buffered I/O offers predictable performance regardless of the platform +and the backing device. Therefore, it is most always preferable to use buffered +I/O rather than unbuffered I/O for binary datal Text I/O -"""""""" +^^^^^^^^ Text I/O over a binary storage (such as a file) is significantly slower than -binary I/O over the same storage, because it implies conversions from -unicode to binary data using a character codec. This can become noticeable -if you handle huge amounts of text data (for example very large log files). -Also, :meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both -quite slow due to the reconstruction algorithm used. +binary I/O over the same storage, because it requires conversions between +unicode and binary data using a character codec. This can become noticeable +handling huge amounts of text data like large log files. Also, +:meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both quite slow +due to the reconstruction algorithm used. :class:`StringIO`, however, is a native in-memory unicode container and will exhibit similar speed to :class:`BytesIO`. @@ -823,9 +819,8 @@ exhibit similar speed to :class:`BytesIO`. Multi-threading ^^^^^^^^^^^^^^^ -:class:`FileIO` objects are thread-safe to the extent that the operating -system calls (such as ``read(2)`` under Unix) they are wrapping are thread-safe -too. +:class:`FileIO` objects are thread-safe to the extent that the operating system +calls (such as ``read(2)`` under Unix) they wrap are thread-safe too. Binary buffered objects (instances of :class:`BufferedReader`, :class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`) @@ -840,12 +835,13 @@ Reentrancy Binary buffered objects (instances of :class:`BufferedReader`, :class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`) are not reentrant. While reentrant calls will not happen in normal situations, -they can arise if you are doing I/O in a :mod:`signal` handler. If it is -attempted to enter a buffered object again while already being accessed -*from the same thread*, then a :exc:`RuntimeError` is raised. - -The above implicitly extends to text files, since the :func:`open()` -function will wrap a buffered object inside a :class:`TextIOWrapper`. This -includes standard streams and therefore affects the built-in function -:func:`print()` as well. +they can arise from doing I/O in a :mod:`signal` handler. If a thread tries to +renter a buffered object which it is already accessing, a :exc:`RuntimeError` is +raised. Note this doesn't prohibit a different thread from entering the +buffered object. + +The above implicitly extends to text files, since the :func:`open()` function +will wrap a buffered object inside a :class:`TextIOWrapper`. This includes +standard streams and therefore affects the built-in function :func:`print()` as +well. -- 2.40.0