diff --git a/doc/faq.xml b/doc/faq.xml index 4387c0cc..21b690c3 100644 --- a/doc/faq.xml +++ b/doc/faq.xml @@ -1,45 +1,49 @@ - %threads.entities; + + %thread.entities; ]> -
+ +
Frequently Asked Questions Are lock objects thread safe? + linkend="thread.glossary.thread-safe">thread safe? No! Lock objects are not meant to be shared between threads. They are meant to be short-lived objects created on automatic storage within a code block. Any other usage is just likely to lead to errors and won't really be of actual benefit anyway. - Share Mutexes, not + Share Mutexes, not Locks. For more information see the rationale behind the + linkend="thread.rationale.locks">rationale behind the design for lock objects. - Why was &Boost.Threads; modeled after (specific library + Why was &Boost.Thread; modeled after (specific library name)? - It wasn't. &Boost.Threads; was designed from scratch. Extensive + It wasn't. &Boost.Thread; was designed from scratch. Extensive design discussions involved numerous people representing a wide range of experience across many platforms. To ensure portability, the initial implements were done in parallel using POSIX Threads and the Win32 - threading API. But the &Boost.Threads; design is very much in the spirit + threading API. But the &Boost.Thread; design is very much in the spirit of C++, and thus doesn't model such C based APIs. - Why wasn't &Boost.Threads; modeled after (specific library + Why wasn't &Boost.Thread; modeled after (specific library name)? @@ -54,12 +58,12 @@ - Why do Mutexes + Why do Mutexes have noncopyable semantics? To ensure that deadlocks don't occur. The + linkend="thread.glossary.deadlock">deadlocks don't occur. The only logical form of copy would be to use some sort of shallow copy semantics in which multiple mutex objects could refer to the same mutex state. This means that if ObjA has a mutex object as part of its state @@ -73,20 +77,20 @@ How can you prevent deadlock from occurring when + linkend="thread.glossary.deadlock">deadlock from occurring when a thread must lock multiple mutexes? Always lock them in the same order. One easy way of doing this is to use each mutex's address to determine the order in which they are - locked. A future &Boost.Threads; concept may wrap this pattern up in a + locked. A future &Boost.Thread; concept may wrap this pattern up in a reusable class. Don't noncopyable Mutex semantics mean that a + linkend="thread.concepts.mutexes">Mutex semantics mean that a class with a mutex member will be noncopyable as well? @@ -94,7 +98,7 @@ copy constructor and assignment operator, so they will have to be coded explicitly. This is a good thing, however, since the compiler generated operations would not be thread-safe. The following + linkend="thread.glossary.thread-safe">thread-safe. The following is a simple example of a class with copyable semantics and internal synchronization through a mutex member. @@ -144,7 +148,7 @@ private: How can you lock a Mutex member in a const member + linkend="thread.concepts.mutexes">Mutex member in a const member function, in order to implement the Monitor Pattern? @@ -165,8 +169,8 @@ private: Condition variables result in user code much less prone to race conditions than - event variables. See + linkend="thread.glossary.race-condition">race conditions than + event variables. See for analysis. Also see &cite.Hoare74; and &cite.SchmidtStalRohnertBuschmann;. @@ -177,7 +181,7 @@ private: There's a valid need for thread termination, so at some point - &Boost.Threads; probably will include it, but only after we can find a + &Boost.Thread; probably will include it, but only after we can find a truly safe (and portable) mechanism for this concept. @@ -206,5 +210,26 @@ private: condition variable. + + + Why doesn't the thread's ctor take at least a void* to pass any + information along with the function? All other threading libs support + that and it makes Boost.Threads inferiour. + + + There is no need, because Boost.Threads are superiour! First + thing is that its ctor doesn't take a function but a functor. That + means that you can pass an object with an overloaded operator() and + include additional data as members in that object. Beware though that + this object is copied, use boost::ref to prevent that. Secondly, even + a boost::function can carry parameters, you only have to + use boost::bind() to create it from any function and bind its + parameters. + That is also why Boost.Threads are superiour, because they + don't require you to pass a type-unsafe void pointer. Rather, you can + use the flexible Boost.Functions to create a thread entry out of + anything that can be called. + +
diff --git a/include/boost/thread/exceptions.hpp b/include/boost/thread/exceptions.hpp index 45cf191f..9b27d312 100644 --- a/include/boost/thread/exceptions.hpp +++ b/include/boost/thread/exceptions.hpp @@ -1,13 +1,8 @@ // Copyright (C) 2001-2003 // William E. Kempf // -// Permission to use, copy, modify, distribute and sell this software -// and its documentation for any purpose is hereby granted without fee, -// provided that the above copyright notice appear in all copies and -// that both that copyright notice and this permission notice appear -// in supporting documentation. William E. Kempf makes no representations -// about the suitability of this software for any purpose. -// It is provided "as is" without express or implied warranty. +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) #ifndef BOOST_THREAD_EXCEPTIONS_PDM070801_H #define BOOST_THREAD_EXCEPTIONS_PDM070801_H @@ -36,8 +31,6 @@ public: int native_error() const; - const char* message() const; - private: int m_sys_err; }; diff --git a/src/exceptions.cpp b/src/exceptions.cpp index 766a9387..88813036 100644 --- a/src/exceptions.cpp +++ b/src/exceptions.cpp @@ -1,13 +1,8 @@ // Copyright (C) 2001-2003 // William E. Kempf // -// Permission to use, copy, modify, distribute and sell this software -// and its documentation for any purpose is hereby granted without fee, -// provided that the above copyright notice appear in all copies and -// that both that copyright notice and this permission notice appear -// in supporting documentation. William E. Kempf makes no representations -// about the suitability of this software for any purpose. -// It is provided "as is" without express or implied warranty. +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) #include @@ -15,57 +10,6 @@ #include #include -# ifdef BOOST_NO_STDC_NAMESPACE -namespace std { using ::strerror; } -# endif - -// BOOST_POSIX or BOOST_WINDOWS specify which API to use. -# if !defined( BOOST_WINDOWS ) && !defined( BOOST_POSIX ) -# if defined(_WIN32) || defined(__WIN32__) || defined(WIN32) || defined(__CYGWIN__) -# define BOOST_WINDOWS -# else -# define BOOST_POSIX -# endif -# endif - -# if defined( BOOST_WINDOWS ) -# include "windows.h" -# else -# include // for POSIX error codes -# endif - -namespace -{ - -std::string system_message(int sys_err_code) -{ - std::string str; -# ifdef BOOST_WINDOWS - LPVOID lpMsgBuf; - ::FormatMessageA(FORMAT_MESSAGE_ALLOCATE_BUFFER | - FORMAT_MESSAGE_FROM_SYSTEM | - FORMAT_MESSAGE_IGNORE_INSERTS, - NULL, - sys_err_code, - MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language - (LPSTR)&lpMsgBuf, - 0, - NULL); - str += static_cast(lpMsgBuf); - ::LocalFree(lpMsgBuf); // free the buffer - while (str.size() && (str[str.size()-1] == '\n' || - str[str.size()-1] == '\r')) - { - str.erase(str.size()-1); - } -# else - str += std::strerror(errno); -# endif - return str; -} - -} // unnamed namespace - namespace boost { thread_exception::thread_exception() @@ -87,13 +31,6 @@ int thread_exception::native_error() const return m_sys_err; } -const char* thread_exception::message() const -{ - if (m_sys_err != 0) - return system_message(m_sys_err).c_str(); - return what(); -} - lock_error::lock_error() { } diff --git a/test/Jamfile.v2 b/test/Jamfile.v2 index bc2bd22a..366814d1 100644 --- a/test/Jamfile.v2 +++ b/test/Jamfile.v2 @@ -1,7 +1,6 @@ -# (C) Copyright William E. Kempf 2001. Permission to copy, use, modify, sell -# and distribute this software is granted provided this copyright notice -# appears in all copies. This software is provided "as is" without express or -# implied warranty, and with no claim as to its suitability for any purpose. +# (C) Copyright William E. Kempf 2001. +# Distributed under the Boost Software License, Version 1.0. (See accompanying +# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) # # Boost.Threads test Jamfile # @@ -19,7 +18,7 @@ import testing ; project - : requirements ../../test/build//boost_unit_test_framework + : requirements /boost/test//boost_unit_test_framework/static multi ;