documented 2nd prototype of wxListCtrl::SetItem

[wxWidgets.git] / docs / latex / wx / thread.tex

diff --git a/docs/latex/wx/thread.tex b/docs/latex/wx/thread.tex
index b487d8178bbf19380a624352631c3a5fcc73c99c..001281e5fdbb3cf07c716f1694d207df40fd3e62 100644 (file)
--- a/docs/latex/wx/thread.tex
+++ b/docs/latex/wx/thread.tex
@@ -8,6 +8,25 @@ much easier to share common data between several threads, it also makes much
 easier to shoot oneself in the foot, so careful use of synchronization objects
 such as \helpref{mutexes}{wxmutex} and/or \helpref{critical sections}{wxcriticalsection} is recommended.
 
+There are two types of threads in wxWindows: {\it detached} and {\it joinable}
+ones, just as in POSIX thread API (but unlike Win32 threads where all threads
+are joinable). The difference between the two is that only joinbale threads
+can return a return code - it is returned by Wait() function. The detached
+threads (default) can not be waited for.
+
+You shouldn't hurry to create all the threads joinable, however, because this
+has a disadvantage as well: you {\bf must} Wait() for a joinable thread of the
+system resources used by it will never be freed and you also must delete the
+corresponding wxThread object yourself, while detached threads are of the
+"fire-and-forget" kind: you only have to start a detached thread and it will
+terminate and destroy itself.
+
+This means, of course, that all detached threads {\bf must} be created on the
+heap because the thread will call {\tt delete this;} upon termination. The
+joinable threads may be created on stack (don't create global thread objects
+because they allocate memory in their constructor which is a badthing to do),
+although usually they will be created on the heap as well.
+
 \wxheading{Derived from}
 
 None.
@@ -84,6 +103,12 @@ created. Moreover, it must be called if \helpref{Create}{wxthreadcreate} or
 occupied by the thread object (it will be done in the destructor for joinable
 threads).
 
+Delete() may be called for thread in any state: running, paused or even not yet created. Moreover,
+it must be called if \helpref{Create}{wxthreadcreate} or \helpref{Run}{wxthreadrun} fail to free
+the memory occupied by the thread object. However, you should not call Delete()
+on a detached thread which already terminated - doing so will probably result
+in a crash because the thread object doesn't exist any more.
+
 For detached threads Delete() will also delete the C++ thread object, but it
 will not do this for joinable ones.
 
@@ -102,6 +127,16 @@ joinable threads and is the value returned by \helpref{Wait}{wxthreadwait}.
 This function is called by wxWindows itself and should never be called
 directly.
 
+\membersection{wxThread::GetCPUCount}\label{wxthreadgetcpucount}
+
+\func{static int}{GetCPUCount}{\void}
+
+Returns the number of system CPUs or -1 if the value is unknown.
+
+\wxheading{See also}
+
+\helpref{SetConcurrency}{wxthreadsetconcurrency}
+
 \membersection{wxThread::GetId}\label{wxthreadgetid}
 
 \constfunc{unsigned long}{GetId}{\void}
@@ -228,6 +263,17 @@ Resumes a thread suspended by the call to \helpref{Pause}{wxthreadpause}.
 
 This function can only be called from another thread context.
 
+\membersection{wxThread::SetConcurrency}\label{wxthreadsetconcurrency}
+
+\func{static bool}{SetConcurrency}{\param{size\_t }{level}}
+
+Sets the thread concurrency level for this process. This is, roughly, the
+number of threads that the system tries to schedule to run in parallel.
+The value of $0$ for {\it level} may be used to set the default one.
+
+Returns TRUE on success or FALSE otherwise (for example, if this function is
+not implemented for this platform (currently everything except Solaris)).
+
 \membersection{wxThread::TestDestroy}\label{wxthreadtestdestroy}
 
 \func{bool}{TestDestroy}{\void}
@@ -263,3 +309,4 @@ Waits until the thread terminates and returns its exit code or {\tt
 You can only Wait() for joinable (not detached) threads.
 
 This function can only be called from another thread context.
+