diff options
| author | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-07-10 15:24:15 -0500 |
|---|---|---|
| committer | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-07-10 15:24:15 -0500 |
| commit | bd0f3345a938b35ce6a12f6150373b0955b8dd12 (patch) | |
| tree | 7a520322212d48ebcb9fbe1087e7fca28b76185c /doc/html/qthreadstorage.html | |
| download | qt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.tar.gz qt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.zip | |
Add Qt3 development HEAD version
Diffstat (limited to 'doc/html/qthreadstorage.html')
| -rw-r--r-- | doc/html/qthreadstorage.html | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/doc/html/qthreadstorage.html b/doc/html/qthreadstorage.html new file mode 100644 index 0000000..ab3c713 --- /dev/null +++ b/doc/html/qthreadstorage.html @@ -0,0 +1,189 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qthreadstorage_unix.cpp:163 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>QThreadStorage Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QThreadStorage Class Reference</h1> + +<p>The QThreadStorage class provides per-thread data storage. +<a href="#details">More...</a> +<p>All the functions in this class are <a href="threads.html#threadsafe">thread-safe</a> when Qt is built with thread support.</p> +<p><tt>#include <<a href="qthreadstorage-h.html">qthreadstorage.h</a>></tt> +<p><a href="qthreadstorage-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn><a href="#QThreadStorage"><b>QThreadStorage</b></a> ()</li> +<li class=fn><a href="#~QThreadStorage"><b>~QThreadStorage</b></a> ()</li> +<li class=fn>bool <a href="#hasLocalData"><b>hasLocalData</b></a> () const</li> +<li class=fn>T & <a href="#localData"><b>localData</b></a> ()</li> +<li class=fn>T <a href="#localData-2"><b>localData</b></a> () const</li> +<li class=fn>void <a href="#setLocalData"><b>setLocalData</b></a> ( T data )</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> + + +The QThreadStorage class provides per-thread data storage. +<p> + + +<p> QThreadStorage is a template class that provides per-thread data +storage. +<p> <em>Note that due to compiler limitations, QThreadStorage can only store pointers.</em> +<p> The <a href="#setLocalData">setLocalData</a>() function stores a single thread-specific value +for the calling thread. The data can be accessed later using the +<a href="#localData">localData</a>() functions. QThreadStorage takes ownership of the +data (which must be created on the heap with <em>new</em>) and deletes +it when the thread exits (either normally or via termination). +<p> The <a href="#hasLocalData">hasLocalData</a>() function allows the programmer to determine if +data has previously been set using the setLocalData() function. +This is useful for lazy initializiation. +<p> For example, the following code uses QThreadStorage to store a +single cache for each thread that calls the <em>cacheObject()</em> and +<em>removeFromCache()</em> functions. The cache is automatically +deleted when the calling thread exits (either normally or via +termination). +<p> <pre> + QThreadStorage<QCache<SomeClass> *> caches; + + void cacheObject( const <a href="qstring.html">QString</a> &key, SomeClass *object ) + { + if ( ! caches.hasLocalData() ) + caches.setLocalData( new <a href="qcache.html">QCache</a><SomeClass> ); + + caches.localData()->insert( key, object ); + } + + void removeFromCache( const <a href="qstring.html">QString</a> &key ) + { + if ( ! caches.hasLocalData() ) + return; // nothing to do + + caches.localData()->remove( key ); + } + </pre> + +<p> <h3> Caveats +</h3> +<a name="1"></a><p> <ul> +<p> <li> As noted above, QThreadStorage can only store pointers due to +compiler limitations. Support for value-based objects will be +added when the majority of compilers are able to support partial +template specialization. +<p> <li> The <a href="#~QThreadStorage">destructor</a> does <em>not</em> +delete per-thread data. QThreadStorage only deletes per-thread +data when the thread exits or when <a href="#setLocalData">setLocalData</a>() is called +multiple times. +<p> <li> QThreadStorage can only be used with threads started with +<a href="qthread.html">QThread</a>. It <em>cannot</em> be used with threads started with +platform-specific APIs. +<p> <li> As a corollary to the above, platform-specific APIs cannot be +used to exit or terminate a QThread using QThreadStorage. Doing so +will cause all per-thread data to be leaked. See <a href="qthread.html#exit">QThread::exit</a>() +and <a href="qthread.html#terminate">QThread::terminate</a>(). +<p> <li> QThreadStorage <em>can</em> be used to store data for the <em>main()</em> +thread <em>after</em> <a href="qapplication.html">QApplication</a> has been constructed. QThreadStorage +deletes all data set for the <em>main()</em> thread when QApplication is +destroyed, regardless of whether or not the <em>main()</em> thread has +actually finished. +<p> <li> The implementation of QThreadStorage limits the total number of +QThreadStorage objects to 256. An unlimited number of threads +can store per-thread data in each QThreadStorage object. +<p> </ul> +<p>See also <a href="environment.html">Environment Classes</a> and <a href="thread.html">Threading</a>. + +<hr><h2>Member Function Documentation</h2> +<h3 class=fn><a name="QThreadStorage"></a>QThreadStorage::QThreadStorage () +</h3> + +<p> Constructs a new per-thread data storage object. + +<h3 class=fn><a name="~QThreadStorage"></a>QThreadStorage::~QThreadStorage () +</h3> + +<p> Destroys the per-thread data storage object. +<p> Note: The per-thread data stored is <em>not</em> deleted. Any data left +in QThreadStorage is leaked. Make sure that all threads using +QThreadStorage have exited before deleting the QThreadStorage. +<p> <p>See also <a href="#hasLocalData">hasLocalData</a>(). + +<h3 class=fn>bool <a name="hasLocalData"></a>QThreadStorage::hasLocalData () const +</h3> + +<p> Returns TRUE if the calling thread has non-zero data available; +otherwise returns FALSE. +<p> <p>See also <a href="#localData">localData</a>(). + +<h3 class=fn>T & <a name="localData"></a>QThreadStorage::localData () +</h3> + +<p> Returns a reference to the data that was set by the calling +thread. +<p> Note: QThreadStorage can only store pointers. This function +returns a <em>reference</em> to the pointer that was set by the calling +thread. The value of this reference is 0 if no data was set by +the calling thread, +<p> <p>See also <a href="#hasLocalData">hasLocalData</a>(). + +<h3 class=fn>T <a name="localData-2"></a>QThreadStorage::localData () const +</h3> + +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Returns a copy of the data that was set by the calling thread. +<p> Note: QThreadStorage can only store pointers. This function +returns a pointer to the data that was set by the calling thread. +If no data was set by the calling thread, this function returns 0. +<p> <p>See also <a href="#hasLocalData">hasLocalData</a>(). + +<h3 class=fn>void <a name="setLocalData"></a>QThreadStorage::setLocalData ( T data ) +</h3> + +<p> Sets the local data for the calling thread to <em>data</em>. It can be +accessed later using the <a href="#localData">localData</a>() functions. +<p> If <em>data</em> is 0, this function deletes the previous data (if +any) and returns immediately. +<p> If <em>data</em> is non-zero, QThreadStorage takes ownership of the <em>data</em> and deletes it automatically either when the thread exits +(either normally or via termination) or when <a href="#setLocalData">setLocalData</a>() is +called again. +<p> Note: QThreadStorage can only store pointers. The <em>data</em> +argument must be either a pointer to an object created on the heap +(i.e. using <em>new</em>) or 0. You should not delete <em>data</em> +yourself; QThreadStorage takes ownership and will delete the <em>data</em> itself. +<p> <p>See also <a href="#localData">localData</a>() and <a href="#hasLocalData">hasLocalData</a>(). + +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">Qt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |