From 60741f92b64bde43514e8a89f67045d347f7194c Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Tue, 9 Oct 2001 22:23:52 +0000 Subject: [PATCH] howto.html: Tweak markup and value type. 2001-10-09 Phil Edwards * docs/html/17_intro/howto.html: Tweak markup and value type. * docs/html/27_io/howto.html: Tweak markup, describe setbuf() for nonzero arguments, add new note on threading. * docs/html/faq/index.html: Update. * docs/html/faq/index.txt: Regenerate. From-SVN: r46130 --- libstdc++-v3/ChangeLog | 8 ++ libstdc++-v3/docs/html/17_intro/howto.html | 3 +- libstdc++-v3/docs/html/27_io/howto.html | 104 +++++++++++++++++++-- libstdc++-v3/docs/html/faq/index.html | 5 +- libstdc++-v3/docs/html/faq/index.txt | 4 +- 5 files changed, 110 insertions(+), 14 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index dc3d498cc13..1397e0f21fc 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,11 @@ +2001-10-09 Phil Edwards + + * docs/html/17_intro/howto.html: Tweak markup and value type. + * docs/html/27_io/howto.html: Tweak markup, describe setbuf() for + nonzero arguments, add new note on threading. + * docs/html/faq/index.html: Update. + * docs/html/faq/index.txt: Regenerate. + 2001-10-09 Phil Edwards * docs/html/configopts.html: More HTML->XHTML and lowercasing of tags. diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index 9831e7cd8e4..27e1a5f663b 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -93,8 +93,7 @@ Here is one possible example displaying the forcing of the malloc-based allocator over the typically higher-speed default allocator: 
-      std::list <void*, std::malloc_alloc>  my_malloc_based_list;
-
+ std::list <my_type, std::malloc_alloc> my_malloc_based_list;

A recent journal article has described "atomic integer operations," which would allow us to, well, perform updates diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index ec516d12db7..c4342a3c4d1 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -29,6 +29,7 @@

  • Deriving a stream buffer
  • More on binary I/O
  • Pathetic performance? Ditch C. +
  • Threads and I/O
    @@ -59,7 +60,7 @@

    Seriously, go do it. Get surprised, then come back. It's worth it.

    -
    +

    The thing to remember is that the basic_[io]stream classes handle formatting, nothing else. In particular, they break up on whitespace. The actual reading, writing, and storing of data is @@ -170,11 +171,14 @@ streambuf does not specify any actions for its own setbuf()-ish functions; the classes derived from streambuf each define behavior that "makes - sense" for that class: an argument of (0,0) turns off - buffering for filebuf but has undefined behavior for - its sibling stringbuf, and specifying anything other - than (0,0) has varying effects. Other user-defined class derived - from streambuf can do whatever they want. + sense" for that class: an argument of (0,0) turns off buffering + for filebuf but has undefined behavior for its sibling + stringbuf, and specifying anything other than (0,0) has + varying effects. Other user-defined class derived from streambuf can + do whatever they want. (For filebuf and arguments for + (p,s) other than zeros, libstdc++ does what you'd expect: + the first s bytes of p are used as a buffer, + which you must allocate and deallocate.)

    A last reminder: there are usually more buffers involved than just those at the language/library level. Kernel buffers, disk @@ -453,10 +457,96 @@ buffered.

    +
    +

    Threads and I/O

    +

    I'll assume that you have already read the + general notes on library threads, + and the + notes on threaded container + access (you might not think of an I/O stream as a container, but + the points made there also hold here). If you have not read them, + please do so first. +

    +

    This gets a bit tricky. Please read carefully, and bear with me. +

    +

    Structure

    +

    As described here, a wrapper + type called __basic_file provides our abstraction layer + for the std::filebuf classes. Nearly all decisions dealing + with actual input and output must be made in __basic_file. +

    +

    A generic locking mechanism is somewhat in place at the filebuf layer, + but is not used in the current code. Providing locking at any higher + level is akin to providing locking within containers, and is not done + for the same reasons (see the links above). +

    +

    The defaults for 3.0.x

    +

    The __basic_file type is simply a collection of small wrappers around + the C stdio layer (again, see the link under Structure). We do no + locking ourselves, but simply pass through to calls to fopen, + fwrite, and so forth. +

    +

    So, for 3.0, the question of "is multithreading safe for I/O" + must be answered with, "is your platform's C library threadsafe + for I/O?" Some are by default, some are not; many offer multiple + implementations of the C library with varying tradeoffs of threadsafety + and efficiency. You, the programmer, are always required to take care + with multiple threads. +

    +

    (As an example, the POSIX standard requires that C stdio FILE* + operations are atomic. POSIX-conforming C libraries (e.g, on Solaris + and GNU/Linux) have an internal mutex to serialize operations on + FILE*s. However, you still need to not do stupid things like calling + fclose(fs) in one thread followed by an access of + fs in another.) +

    +

    So, if your platform's C library is threadsafe, then your + fstream I/O operations will be threadsafe at the lowest + level. For higher-level operations, such as manipulating the data + contained in the stream formatting classes (e.g., setting up callbacks + inside an std::ofstream), you need to guard such accesses + like any other critical shared resource. +

    +

    The future

    +

    As already mentioned here, a + second choice is available for I/O implementations: libio. This is + disabled by default, and in fact will not currently work due to other + issues. It will be revisited, however. +

    +

    The libio code is a subset of the guts of the GNU libc (glibc) I/O + implementation. When libio is in use, the __basic_file + type is basically derived from FILE. (The real situation is more + complex than that... it's derived from an internal type used to + implement FILE. See libio/libioP.h to see scary things done with + vtbls.) The result is that there is no "layer" of C stdio + to go through; the filebuf makes calls directly into the same + functions used to implement fread, fwrite, + and so forth, using internal data structures. (And when I say + "makes calls directly," I mean the function is literally + replaced by a jump into an internal function. Fast but frightening. + *grin*) +

    +

    Also, the libio internal locks are used. This requires pulling in + large chunks of glibc, such as a pthreads implementation, and is one + of the issues preventing widespread use of libio as the libstdc++ + cstdio implementation. +

    +

    But we plan to make this work, at least as an option if not a future + default. Platforms running a copy of glibc with a recent-enough + version will see calls from libstdc++ directly into the glibc already + installed. For other platforms, a copy of the libio subsection will + be built and included in libstdc++. +

    +

    Alternatives

    +

    Don't forget that other cstdio implemenations are possible. You could + easily write one to perform your own forms of locking, to solve your + "interesting" problems. +

    + -








    +

    See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html index b06685a77c1..0b711973a8d 100644 --- a/libstdc++-v3/docs/html/faq/index.html +++ b/libstdc++-v3/docs/html/faq/index.html @@ -686,9 +686,8 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff

    5.6 Is libstdc++-v3 thread-safe?

    -

    Quick answer: no, as of 2.92 (eleventh snapshot), the - library is not appropriate for multithreaded access. The - string class is MT-safe. +

    Quick answer: no, as of 3.0, most of the library is not + safe for multithreaded access. The string class is MT-safe.

    This is assuming that your idea of "multithreaded" is the same as ours... The general question of multithreading diff --git a/libstdc++-v3/docs/html/faq/index.txt b/libstdc++-v3/docs/html/faq/index.txt index 0691da78429..fcf84c8cd83 100644 --- a/libstdc++-v3/docs/html/faq/index.txt +++ b/libstdc++-v3/docs/html/faq/index.txt @@ -548,8 +548,8 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff 5.6 Is libstdc++-v3 thread-safe? - Quick answer: no, as of 2.92 (eleventh snapshot), the library is not - appropriate for multithreaded access. The string class is MT-safe. + Quick answer: no, as of 3.0, most of the library is not safe for + multithreaded access. The string class is MT-safe. This is assuming that your idea of "multithreaded" is the same as ours... The general question of multithreading and libstdc++-v3 is