autodoc.git/ autodoc.xml

Branch: Tag:

1996-10-06

1996-10-06 21:17:38 by Fredrik Hübinette (Hubbe) <hubbe@hubbe.net>

threads documentation

Rev: doc/builtin/thread_create:1.1
Rev: doc/precompiled/condition:1.1
Rev: doc/precompiled/mutex:1.1

5199:      </doc>   </docgroup> + <docgroup homogen-name='thread_create' homogen-type='method'> + <method name='thread_create'/><doc placeholder='true'> + <text> + <p><tt>thread_create</tt> - create a thread</p> +  + <tt><p>int thread_create(function <i>f</i>, mixed ... <i>args</i>);<br/> + </p> + </tt> + <p>This function creates a new thread which will run simultaneously + to the rest of the program. The new thread will call the function + f with the arguments args. When f returns the thread will cease + to exist. All Pike functions are 'thread safe' meanting that running + a function at the same time from different threads will not corrupt + any internal data in the Pike process.</p> + </text> +  + <group><note/><text> + <p>This function is only available on systems with POSIX threads support.</p> + </text></group> +  + <group><seealso/><text> + <p><ref resolved='predef::thread_create' to='/precompiled/mutex'>/precompiled/mutex</ref> and <ref resolved='predef::thread_create' to='/precompiled/condition'>/precompiled/condition</ref></p> + </text></group> +  + </doc> + </docgroup>   <docgroup homogen-name='throw' homogen-type='method'>   <method name='throw'/><doc placeholder='true'>   <text>
5549:      </doc>   </docgroup> + <class name='/precompiled/condition'> + <doc placeholder='true'> + <text> + <p><tt>/precompiled/condition</tt> - condition variables</p> +  + <p>/precompiled/condition is a precompiled Pike program that implements + condition variables. Condition variables are used by threaded programs + to wait for events happening in other threads.</p> + </text> +  + <group><note/><text> + <p>Mutex locks are only available on systems with POSIX threads support.</p> + </text></group> +  + <group><example/><text> + <tt><p>// This program implements a fifo that can be used to send<br/> + // data between two threads.<br/> + inherit "/precompiled/condition": r_cond;<br/> + inherit "/precompiled/condition": w_cond;<br/> + inherit "/precompiled/mutex": lock;<br/> +  + </p> + <p>mixed *buffer = allocate(128);<br/> + int r_ptr, w_ptr;<br/> +  + </p> + <p>int query_messages() { return w_ptr - r_ptr; }<br/> +  + </p> + <p>// This function reads one mixed value from the fifo.<br/> + // If no values are available it blocks until a write has been done.<br/> + mixed read()<br/> + {<br/> + <dl><group><text>mixed tmp;<br/> + // We use this mutex lock to make sure no write() is executed<br/> + // between the query_messages and the wait() call. If it did<br/> + // we would wind up in a deadlock.<br/> + object key=lock::lock();<br/> + while(!query_messages()) r_cond::wait(key);<br/> + tmp=buffer[r_ptr++ % sizeof(buffer)];<br/> + w_cond::signal();<br/> + return tmp;<br/> + </text></group></dl>}<br/> +  + </p> + <p>// This function pushes one mixed value on the fifo.<br/> + // If the fifo is full it blocks until a value has been read.<br/> + void write(mixed v)<br/> + {<br/> + <dl><group><text>object key=lock::lock();<br/> + while(query_messages() == sizeof(buffer)) w_cond::wait(key);<br/> + buffer[w_ptr++ % sizeof(buffer)]=v;<br/> + r_cond::signal();<br/> + </text></group></dl>}<br/> + </p> + </tt></text></group> +  + <group><seealso/><text> + <p><ref resolved='predef::/precompiled/condition' to='/precompiled/mutex'>/precompiled/mutex</ref></p> + </text></group> +  + </doc> + <docgroup homogen-name='broadcast' homogen-type='method'> + <method name='broadcast'> + </method> + <doc placeholder='true'> + <text> + <p><tt>broadcast</tt> - signal all waiting threads</p> +  + <tt><p>void condition-&gt;broadcast();<br/> + </p> + </tt> + <p>This function wakes up all threads currently waiting for this + condition. + </p> + <p/> + </text> +  + </doc> + </docgroup> + <docgroup homogen-name='signal' homogen-type='method'> + <method name='signal'> + </method> + <doc placeholder='true'> + <text> + <p><tt>signal</tt> - signal a condition variable</p> +  + <tt><p>void condition-&gt;signal();<br/> + </p> + </tt> + <p>Signal wakes up one of the threads currently waiting for the + condition.</p> + </text> +  + <group><bugs/><text> + <p>It sometimes wakes up more than one thread. + </p> + <p/> + </text></group> +  + </doc> + </docgroup> + <docgroup homogen-name='wait' homogen-type='method'> + <method name='wait'> + </method> + <doc placeholder='true'> + <text> + <p><tt>wait</tt> - wait for condition</p> +  + <tt><p>void condition-&gt;wait();<br/> + or<br/> + void condition-&gt;wait(object <i>mutex_key</i>);<br/> + </p> + </tt> + <p>This function makes the current thread sleep until the condition + variable is signalled. The optional argument should be the 'key' + to a mutex lock. If present the mutex lock will be unlocked before + waiting for the condition in one atomical operation. After waiting + for the condition the mutex referenced by mutex_key will be re-locked.</p> + </text> +  + <group><seealso/><text> + <p><ref resolved='predef::/precompiled/mutex.lock' to='mutex-&gt;lock'>mutex-&gt;lock</ref></p> + </text></group> +  + </doc> + </docgroup> + </class>   <class name='/precompiled/file'>   <doc placeholder='true'>   <text>
6503:   </doc>   </docgroup>   </class> + <class name='/precompiled/mutex'> + <doc placeholder='true'> + <text> + <p><tt>/precompiled/mutex</tt> - mutex locks</p> +  + <p>/precompiled/mutex is a precompiled Pike program that implements + mutal exclusion locks. Mutex locks are used to prevent multiple + threads from simultaneously execute sections of code which accesses + or changes shared data. The basic operations for a mutex is locking + and unlocking, if a thread attempts to lock an already locked mutex + the thread will sleep until the mutex is unlocked.</p> + </text> +  + <group><note/><text> + <p>Mutex locks are only available on systems with POSIX threads support. + </p> + <p/> + </text></group> +  + </doc> + <docgroup homogen-name='lock' homogen-type='method'> + <method name='lock'> + </method> + <doc placeholder='true'> + <text> + <p><tt>lock</tt> - lock the mutex</p> +  + <tt><p>object mutex-&gt;lock();<br/> + </p> + </tt> + <p>This function attempts to lock the mutex, if the mutex is already + locked current thread will sleep until the lock is unlocked by some + other thread. The value returned is the 'key' to the lock, which the + key is destructed or has no more references the lock will automatically + be unlocked. + </p> + <p/> + </text> +  + </doc> + </docgroup> + <docgroup homogen-name='trylock' homogen-type='method'> + <method name='trylock'> + </method> + <doc placeholder='true'> + <text> + <p><tt>trylock</tt> - try to lock the mutex</p> +  + <tt><p>object mutex-&gt;trylock();<br/> + </p> + </tt> + <p>This function preforms the same operation as lock(), but if the mutex + is already locked zero will be returned instead of sleeping until the + lock is unlocked. + </p> + <p/> + </text> +  + </doc> + </docgroup> + </class>   <class name='/precompiled/port'>   <doc placeholder='true'>   <text>