nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/TheKernelKit_ThreadsAndTeam...

434 lines
72 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Kernel Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheKernelKit.html" title="The Kernel Kit" /><link rel="prev" href="TheKernelKit_Semaphores.html" title="Semaphores" /><link rel="next" href="TheKernelKit_Time.html" title="Time Information" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheKernelKit_Semaphores.html" title="Semaphores"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheKernelKit.html" title="The Kernel Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="TheKernelKit_Time.html" title="Time Information"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Kernel Kit</div></div><div id="headerB">Prev: <a href="TheKernelKit_Semaphores.html">Semaphores</a>  Up: <a href="TheKernelKit.html">The Kernel Kit</a>  Next: <a href="TheKernelKit_Time.html">Time Information</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheKernelKit_ThreadsAndTeams"></a>Threads And Teams</h2></div></div></div><div class="informaltable"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Declared in:</td><td><code class="filename">kernel/OS.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libroot.so</code></td></tr></tbody></table></div><p>A thread is a synchronous process that executes a series of program
instructions. When you launch an application, an initial thread—the
main thread—is automatically created (or spawned) and told to run.
From the main thread you can spawn and run additional threads; from each
of these threads you can spawn and run more threads, and so on. The
collection of threads that are spawned from the main thread—in
other words, the threads that comprise an application—is called a
team. All the threads in all teams run concurrently and asynchronously
with each other.</p><p>For more information on threads and teams, see
"<a class="link" href="TheKernelKit_ThreadsAndTeams_Overview.html" title="Threads And Teams">Threads And Teams Overview</a>".</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="ThreadsAndTeams_Functions"></a>Thread and Team Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="estimate_max_scheduling_latency"></a>estimate_max_scheduling_latency()</h4></div></div></div><a id="id1107730" class="indexterm"></a><p>Declared in: <code class="filename">kernel/scheduler.h</code></p><code class="methodsynopsis c"><span class="type">bigtime_t </span><span class="methodname">estimate_max_scheduling_latency</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span><span class="initializer"> = -1</span></span>);</code><p>Returns the scheduling latency, in microseconds, of the specified thread.
Specify a <span class="type">thread_id</span> of -1 to return the scheduling latency of the current
thread.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="exit_thread"></a><a id="kill_thread"></a>
<a id="kill_team"></a>
<a id="on_exit_thread"></a>
exit_thread(), kill_thread(), kill_team(), on_exit_thread()</h4></div></div></div><a id="id1107806" class="indexterm"></a><a id="id1107813" class="indexterm"></a><a id="id1107820" class="indexterm"></a><a id="id1107826" class="indexterm"></a><code class="methodsynopsis c"><span class="type">void </span><span class="methodname">exit_thread</span>(<span class="methodparam"><span class="type">status_t </span><span class="parameter">return_value</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">kill_thread</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">kill_team</span>(<span class="methodparam"><span class="type">team_id </span><span class="parameter">team</span></span>);</code><pre class="programlisting c"><span class="type">status_t</span> <code class="function">on_exit_thread</code>(<span class="type">void</span> (*<code class="parameter">callback</code>)(<span class="type">void *</span>), <span class="type">void *</span><code class="parameter">data</code>)</pre><p>These functions command one or more threads to halt execution:</p><table class="variablelist functions"><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="function">exit_thread()</code></span></p></td><td><p>Tells the calling thread to exit with a return value as
given by the argument. Declaring the return value is only useful if
some other thread is sitting in a
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#wait_for_thread" title="wait_for_thread()"><code class="function">wait_for_thread()</code></a>
call on this thread. <code class="function">exit_thread()</code> sends a signal to the thread (after caching the
return value in a known place).</p></td></tr><tr><td><p><span class="term"><code class="function">kill_thread()</code></span></p></td><td><p>Kills the thread given by the argument. The value that
the thread will return to
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#wait_for_thread" title="wait_for_thread()"><code class="function">wait_for_thread()</code></a>
is undefined and can't be relied upon. <code class="function">kill_thread()</code>
is the same as sending a <span class="signal">SIGKILLTHR</span> signal to the thread.</p></td></tr><tr><td><p><span class="term"><code class="function">kill_team()</code></span></p></td><td><p>Kills all the threads within the given team. Again, the
threads' return values are random. <code class="function">kill_team()</code> is the same as sending a
<span class="signal">SIGKILL</span> signal to any thread in the team. Each of the threads in the
team is then handed a <span class="signal">SIGKILLTHR</span> signal.</p></td></tr><tr><td><p><span class="term"><code class="function">on_exit_thread()</code></span></p></td><td><p>Sets up the specified callback to be executed when
the calling thread exits. The callback will receive the pointer data as
an input argument.</p></td></tr></tbody></table><p>Exiting a thread is a fairly safe thing to do—since a thread can
only exit itself, it's assumed that the thread knows what it's doing.
Killing some other thread or an entire team is a bit more drastic since
the death certificate(s) will be delivered at an indeterminate time. In
addition, killing a thread can leak memory since resources that were
allocated by the thread may not be freed. Killing an entire team, on the
other hand, won't leak since the system reclaims all resources when the
team dies.</p><p>Keep in mind that threads die automatically (and their resources are
reclaimed) if they're allowed to exit naturally. You should only need to
kill a thread if something has gone screwy.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The thread or team was successfully killed.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_ID</code>.</span></p></td><td><p>Invalid thread value.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_TEAM_ID</code>.</span></p></td><td><p>Invalid team value.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>Returned by
<code class="function">on_exit_thread()</code> if there's no memory to
construct the internal callback record.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="find_thread"></a>find_thread()</h4></div></div></div><a id="id1108159" class="indexterm"></a><code class="methodsynopsis c"><span class="type">thread_id </span><span class="methodname">find_thread</span>(<span class="methodparam"><span class="type">const char* </span><span class="parameter">name</span></span>);</code><p>Finds and returns the thread with the given <code class="parameter">name</code>. A
<code class="parameter">name</code> argument of <code class="constant">NULL</code>
returns the calling thread.</p><p>A thread's name is assigned when the thread is spawned. The name can be
changed thereafter through the
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#rename_thread" title="rename_thread()"><code class="function">rename_thread()</code></a>
function. Keep in mind
that thread names needn't be unique: If two (or more) threads boast the
same name, a <code class="function">find_thread()</code> call on that name returns the first so-named
thread that it finds. There's no way to iterate through identically-named
threads.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code>.</span></p></td><td><p><code class="parameter">name</code>
doesn't identify a valid thread.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="get_team_info"></a><a id="get_next_team_info"></a>
get_team_info(), get_next_team_info()</h4></div></div></div><a id="id1108263" class="indexterm"></a><a id="id1108270" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_team_info</span>(<span class="methodparam"><span class="type">team_id </span><span class="parameter">team</span></span>,<br />                       <span class="methodparam"><span class="type">team_info* </span><span class="parameter">info</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_next_team_info</span>(<span class="methodparam"><span class="type">int32* </span><span class="parameter">cookie</span></span>,<br />                            <span class="methodparam"><span class="type">team_info* </span><span class="parameter">info</span></span>);</code><p>The functions copy, into the <code class="parameter">info</code>
argument, the
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#team_info" title="team_info"><span class="type">team_info</span></a> structure for a
particular team. The <code class="function">get_team_info()</code> function retrieves information for
the team identified by <code class="parameter">team</code>. For information about the kernel, use
<code class="constant">B_SYSTEM_TEAM</code> as the team argument.</p><p>The <code class="function">get_next_team_info()</code> version lets you step through the list of all
teams. The <code class="parameter">cookie</code> argument is a placemark; you set it to 0 on your first
call, and let the function do the rest. The function returns <code class="constant">B_BAD_VALUE</code>
when there are no more areas to visit:</p><pre class="programlisting example cpp"><span class="comment">/* Get the team_info for every team. */</span>
<span class="type">team_info</span> <code class="varname">info</code>;
<span class="type">int32</span> <code class="varname">cookie</code> = 0;
while (<code class="function">get_next_team_info</code>(0, &amp;<code class="varname">cookie</code>, &amp;<code class="varname">info</code>) == <code class="constant">B_OK</code>)
...</pre><p>See
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#team_info" title="team_info"><span class="type">team_info</span></a>
for a description of that structure.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The desired team information was found.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_TEAM_ID</code>.</span></p></td><td><p><code class="parameter">team</code>
doesn't identify an existing team, or there are no more areas to
visit.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="get_thread_info"></a><a id="get_next_thread_info"></a>
get_thread_info(), get_next_thread_info()</h4></div></div></div><a id="id1108497" class="indexterm"></a><a id="id1108504" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_thread_info</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>,<br />                         <span class="methodparam"><span class="type">thread_info* </span><span class="parameter">info</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_next_thread_info</span>(<span class="methodparam"><span class="type">team_id </span><span class="parameter">team</span></span>,<br />                              <span class="methodparam"><span class="type">int32* </span><span class="parameter">cookie</span></span>,<br />                              <span class="methodparam"><span class="type">thread_info* </span><span class="parameter">info</span></span>);</code><p>These functions copy, into the <code class="parameter">info</code>
argument, the
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#thread_info" title="thread_info"><span class="type">thread_info</span></a>
structure for a particular thread:</p><p>The <code class="function">get_thread_info()</code> function gets the
information for the thread identified by <code class="parameter">thread</code>.</p><p>The <code class="function">get_next_thread_info()</code> function lets you step through the list of a
team's threads through iterated calls. The <code class="parameter">team</code> argument identifies the
team you want to look at; a <code class="parameter">team</code> value of 0 means the team of the calling
thread. The <code class="parameter">cookie</code> argument is a placemark; you set it to 0 on your first
call, and let the function do the rest. The function returns <code class="constant">B_BAD_VALUE</code>
when there are no more threads to visit:</p><pre class="programlisting example cpp"><span class="comment">/* Get the thread_info for every thread in this team. */</span>
<span class="type">thread_info</span> <code class="varname">info</code>;
<span class="type">int32</span> <code class="varname">cookie</code> = 0;
while (<code class="function">get_next_thread_info</code>(0, &amp;<code class="varname">cookie</code>, &amp;<code class="varname">info</code>) == <code class="constant">B_OK</code>)
...</pre><p>The value of the <code class="varname">priority</code> field describes the thread's "urgency"; the
higher the value, the more urgent the thread. The more urgent the thread,
the more attention it gets from the CPU. Expected priority values fall
between 0 and 120.
See "<a class="link" href="TheKernelKit_ThreadsAndTeams.html#Constants_ThreadPriorities" title="Thread Priority Values">Thread Priorities</a>"
for the full story.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text">
Thread info is provided primarily as a debugging aid. None of the
values that you find in a <span class="type">thread_info</span> structure are guaranteed to be
valid—the thread's state, for example, will almost certainly have
changed by the time <code class="function">get_thread_info()</code> returns.
</div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The thread was found;
<code class="parameter">info</code> contains valid information.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><p><code class="parameter">thread</code>
doesn't identify an existing thread, <code class="parameter">team</code> doesn't
identify an existing team, or there are no more threads to visit.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="rename_thread"></a>rename_thread()</h4></div></div></div><a id="id1108774" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">rename_thread</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>,<br />                       <span class="methodparam"><span class="type">const char* </span><span class="parameter">name</span></span>);</code><p>Changes the name of the given thread to <code class="parameter">name</code>. The name can be no longer
than <code class="constant">B_OS_NAME_LENGTH</code> (32 characters).</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The thread was successfully named.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_ID</code>.</span></p></td><td><p><code class="parameter">thread</code>
argument isn't a valid <span class="type">thread_id</span> number.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="resume_thread"></a>resume_thread()</h4></div></div></div><a id="id1108882" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">resume_thread</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>);</code><p>Tells a new or suspended thread to begin executing instructions. If the
thread has just been spawned, it enters and executes the thread function
declared in <a class="link" href="TheKernelKit_ThreadsAndTeams.html#spawn_thread" title="spawn_thread()"><code class="function">spawn_thread()</code></a>.
If the thread was previously suspended(through
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#suspend_thread" title="suspend_thread()"><code class="function">suspend_thread()</code></a>),
it continues from where it was suspended.</p><p>You can't use this function to wake up a sleeping thread, or to unblock a
thread that's waiting to acquire a semaphore or waiting in a
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>
call. However, you can unblock any of these threads by
suspending and then resuming. Blocked threads that are resumed return
<code class="constant">B_INTERRUPTED</code>.</p><p><code class="function">resume_thread()</code> is the same as sending a
<span class="signal">SIGCONT</span> signal to the thread.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>
The thread was successfully resumed.
</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_ID</code>.</span></p></td><td><p>
<code class="parameter">thread</code> argument isn't a valid
<span class="type">thread_id</span> number.
</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_STATE</code>.</span></p></td><td><p>
The thread isn't suspended.
</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="receive_data"></a>receive_data()</h4></div></div></div><a id="id1109031" class="indexterm"></a><code class="methodsynopsis c"><span class="type">int32 </span><span class="methodname">receive_data</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">sender</span></span>,<br />                   <span class="methodparam"><span class="type">void* </span><span class="parameter">buffer</span></span>,<br />                   <span class="methodparam"><span class="type">size_t </span><span class="parameter">buffer_size</span></span>);</code><p>Retrieves a message from the thread's message cache. The message will
have been placed there through a previous
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a>
function call. If the cache is empty, <code class="function">receive_data()</code>
blocks until one shows up—it never returns empty-handed.</p><p>The <span class="type">thread_id</span> of the thread that called
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a>
is returned by reference in the sender argument. Note that there's no guarantee that the
sender will still be alive by the time you get its ID. Also, the value of
sender going into the function is ignored—you can't ask for a
message from a particular sender.</p><p>The
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a>
function copies two pieces of data into a thread's
message cache:</p><ul class="itemizedlist"><li><p>A single four-byte code that's delivered as
<code class="function">receive_data()</code>'s return value,</p></li><li><p>and an arbitrarily long data buffer that's copied into
<code class="function">receive_data()</code>'s buffer argument (you must allocate and free buffer
yourself). The <code class="parameter">buffer_size</code> argument tells the function how many bytes
of data to copy. If you don't need the data buffer—if the code
value returned directly by the function is sufficient—you set
<code class="parameter">buffer</code> to <code class="constant">NULL</code> and
<code class="parameter">buffer_size</code> to 0.</p></li></ul><p>Unfortunately, there's no way to tell how much data is in the cache
before you call <code class="function">receive_data()</code>:</p><ul class="itemizedlist"><li><p>If there's more data than buffer can accommodate, the unaccommodated
portion is discarded—a second <code class="function">receive_data()</code> call will not read
the rest of the message.</p></li><li><p>Conversely, if <code class="function">receive_data()</code> asks for more data than was sent, the
function returns with the excess portion of buffer
unmodified—<code class="function">receive_data()</code> doesn't wait for another
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a>
call to provide more data with which to fill up the buffer.</p></li></ul><p>Each receive_data() corresponds to exactly one
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a>.
Lacking a previous invocation of its mate, <code class="function">receive_data()</code> will block until
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a>
is called. If you don't want to block, you should call
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#has_data" title="has_data()"><code class="function">has_data()</code></a>
before calling <code class="function">receive_data()</code> (and proceed to
<code class="function">receive_data()</code>
only if <a class="link" href="TheKernelKit_ThreadsAndTeams.html#has_data" title="has_data()"><code class="function">has_data()</code></a>
returns <code class="constant">true</code>).</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term">If successful</span></p></td><td><p>Returns the message's four-byte code.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_INTERRUPTED</code>.</span></p></td><td><p>A blocked <code class="function">receive_data()</code> call was interrupted by a
signal.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="send_data"></a>send_data()</h4></div></div></div><a id="id1109324" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">send_data</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">sender</span></span>,<br />                   <span class="methodparam"><span class="type">void* </span><span class="parameter">buffer</span></span>,<br />                   <span class="methodparam"><span class="type">size_t </span><span class="parameter">buffer_size</span></span>);</code><p><code class="function">send_data()</code> copies a message into thread's message cache. The target
thread retrieves the message (and empties the cache) by calling
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>.</p><p>There are two parts to the message:</p><ul class="itemizedlist"><li><p>A single four-byte code passed as an argument to
<code class="function">send_data()</code> and returned directly by
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>.</p></li><li><p>A <code class="parameter">buffer</code> of data that's
<code class="parameter">buffer_size</code> bytes long
(<code class="parameter">buffer</code> can be <code class="constant">NULL</code>, in which
case <code class="parameter">buffer_size</code> should be 0). The data is copied
into the target thread's cache, and then copied into
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>'s
<code class="parameter">buffer</code> (which must be allocated). The calling
threads retain responsibility for freeing their buffers.</p></li></ul><p>In addition to returning the <code class="parameter">code</code> directly, and copying the message data
into its <code class="parameter">buffer</code> argument,
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>
sets <code class="parameter">sender</code> to the id of the thread that sent the message.</p><p><code class="function">send_data()</code> blocks if there's an unread message in the target thread's
cache; otherwise it returns immediately (i.e. it doesn't wait for the
target to call <a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>.
Analogously, <a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>
blocks until there's a message to retrieve.</p><p>In the following example, the main thread spawns a thread, sends it a
message, and then tells the thread to run:</p><pre class="programlisting example cpp"><code class="function">main</code>()
{
<span class="type">thread_id</span> <code class="varname">other_thread</code>;
<span class="type">int32</span> <code class="varname">code</code> = 63;
<span class="type">char *</span><code class="varname">buf</code> = "Hello";
<code class="varname">other_thread</code> = <code class="function">spawn_thread</code>(<code class="varname">thread_func</code>, ...);
<code class="function">send_data</code>(<code class="varname">other_thread</code>, <code class="varname">code</code>, (<span class="type">void *</span>)<code class="varname">buf</code>, <code class="function">strlen</code>(<code class="varname">buf</code>));
<code class="function">resume_thread</code>(<code class="varname">other_thread</code>);
...
}</pre><p>To retrieve the message, the target thread calls
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>:</p><pre class="programlisting example cpp"><span class="type">int32</span> <code class="function">thread_func</code>(<span class="type">void *</span><code class="parameter">data</code>)
{
<span class="type">thread_id</span> <code class="varname">sender</code>;
<span class="type">int32</span> <code class="varname">code</code>;
<span class="type">char</span> <code class="varname">buf</code>[512];
<code class="varname">code</code> = <code class="function">receive_data</code>(&amp;<code class="varname">sender</code>, (<span class="type">void *</span>)<code class="varname">buf</code>, <code class="function">sizeof</code>(<code class="varname">buf</code>));
...
}</pre><p>Keep in mind that the message data is copied into the buffer; you must
allocate adequate storage for the data. If the buffer isn't big enough to
accommodate all the datain the message, the left-over portion is thrown
away. Note, however, that there isn't any way for a thread to determine
how much data has been copied into its message cache.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The data was successfuly sent.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_ID</code>.</span></p></td><td><p><code class="parameter">thread</code> doesn't identify a valid thread.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>The target couldn't allocate enough memory for its copy
of buffer.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_INTERRUPTED</code>.</span></p></td><td><p>The function blocked, but a signal unblocked it.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="has_data"></a>has_data()</h4></div></div></div><a id="id1109760" class="indexterm"></a><code class="methodsynopsis c"><span class="type">bool </span><span class="methodname">has_data</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>);</code><p><code class="function">has_data()</code> returns <code class="constant">true</code> if
<code class="parameter">thread</code> has a message in its message cache.
Ostensibly, you use this function before calling
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a> or
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>
to avoid blocking:</p><pre class="programlisting example cpp">if (!<code class="function">has_data</code>(<code class="varname">target_thread</code>))
<code class="varname">err</code> = <code class="function">send_data</code>(<code class="varname">target_thread</code>, ...);
<span class="comment">/* or */</span>
if (<code class="function">has_data</code>(<code class="function">find_thread</code>(<code class="varname">NULL</code>))
<code class="varname">code</code> = <code class="function">receive_data</code>(...);</pre><p>This works for
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>,
but notice that there's a race condition between the
<code class="function">has_data()</code> and
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#send_data" title="send_data()"><code class="function">send_data()</code></a>
calls. Another thread could send a message to the target in the interim.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="set_thread_priority"></a><a id="suggest_thread_priority"></a>
set_thread_priority(), suggest_thread_priority()</h4></div></div></div><a id="id1109906" class="indexterm"></a><a id="id1109914" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">set_thread_priority</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>,<br />                             <span class="methodparam"><span class="type">int32 </span><span class="parameter">new_priority</span></span>);</code><code class="methodsynopsis c"><span class="type">int32 </span><span class="methodname">suggest_thread_priority</span>(<span class="methodparam"><span class="type">uint32 </span><span class="parameter">what</span><span class="initializer"> = <span class="constant">B_DEFAULT_MEDIA_PRIORITY</span></span></span>,<br />                              <span class="methodparam"><span class="type">int32 </span><span class="parameter">period</span><span class="initializer"> = <span class="constant">0</span></span></span>,<br />                              <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">jitter</span><span class="initializer"> = <span class="constant">0</span></span></span>,<br />                              <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">length</span><span class="initializer"> = <span class="constant">0</span></span></span>);</code><p>Declared in: <code class="filename">kernel/scheduler.h</code></p><p><code class="function">set_thread_priority()</code> resets the given thread's priority to <code class="parameter">new_priority</code>.
The priority is expected to be between 0 and 120.
See "Thread Priorities"
for a description of the priority scheme, and
"Thread Priority Values"
for a list of pre-defined priority constants.</p><p><code class="function">suggest_thread_priority()</code> takes information about a thread and returns a
suggested priority that you can pass to <code class="function">set_thread_priority()</code> (or, more
likely, to
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#spawn_thread" title="spawn_thread()"><code class="function">spawn_thread()</code></a>).</p><p>The <code class="parameter">what</code> value is a bit mask that indicates the type of activities the
thread will be used for. The possible values are listed in
Suggested Thread Priorities.</p><p><code class="parameter">period</code> is the number of times per second the thread needs to be run
(specify 0 if it needs to run continuously). <code class="parameter">jitter</code> is an estimate, in
microseconds, of how much the period can vary as long as the average
stays at <code class="parameter">period</code> times per second.</p><p><code class="parameter">length</code> is an approximation of the amount of time, in microseconds, the
thread will typically run per invocation (i.e., the amount of time that
will pass between the moment it receives a message, through processing
it, until it's again waiting for another message).</p><p>For example, if you're spawning a thread to handle video refresh for a
computer game, and you want the display to update 30 times per second,
you might use code similar to the following:</p><pre class="programlisting example cpp"><span class="type">int32</span> <code class="varname">priority</code>;
<code class="varname">priority</code> = <code class="function">suggest_thread_priority</code>(<code class="constant">B_LIVE_3D_RENDERING</code>, 30, 1000, 150);
<code class="varname">th</code> = <code class="function">spawn_thread</code>(<code class="varname">func</code>, "render_thread", <code class="varname">priority</code>, <code class="constant">NULL</code>)</pre><p>This spawns the rendering thread with a priority appropriate for a thread
for live 3D rendering which wants to be run 30 times per second, with a
variation of only 1000 microseconds. Each invocation of the thread's code
is estimated to take 150 microseconds. Obviously the jitter and length
values would have to be tuned to the particular application.</p><p><code class="function">set_thread_priority()</code> returns…</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term">Positive integers.</span></p></td><td><p>If the function is successful, the previous priority
is returned.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_ID</code>.</span></p></td><td><code class="parameter">thread</code> doesn't identify a valid thread.
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="snooze"></a><a id="snooze_until"></a>
snooze(), snooze_until()</h4></div></div></div><a id="id1110220" class="indexterm"></a><a id="id1110227" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">snooze</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">microseconds</span></span>,<br />                <span class="methodparam"><span class="type">int32 </span><span class="parameter">new_priority</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">snooze_until</span>(<span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">microseconds</span></span>,<br />                      <span class="methodparam"><span class="type">int </span><span class="parameter">timebase</span></span>);</code><p><code class="function">snooze()</code> blocks the calling thread for
the given number of <code class="parameter">microseconds</code>.</p><p><code class="function">snooze_until()</code> blocks until an absolute time measured in the given
<code class="parameter">timebase</code>. Currently, the only allowed value for <code class="parameter">timebase</code> is
<code class="constant">B_SYSTEM_TIMEBASE</code>, which measures time against the system clock (as
reported by <a class="link" href="TheKernelKit_Time.html#system_time" title="system_time()"><code class="function">system_time()</code></a>).</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td>
The thread went to sleep and is now awake.
</td></tr><tr><td><p><span class="term"><code class="constant">B_INTERRUPTED</code>.</span></p></td><td>
The thread received a signal while it was sleeping.
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="spawn_thread"></a>spawn_thread()</h4></div></div></div><a id="id1110376" class="indexterm"></a><code class="methodsynopsis c"><span class="type">thread_id </span><span class="methodname">spawn_thread</span>(<span class="methodparam"><span class="type">thread_func </span><span class="parameter">func</span></span>,<br />                       <span class="methodparam"><span class="type">const char* </span><span class="parameter">name</span></span>,<br />                       <span class="methodparam"><span class="type">int32 </span><span class="parameter">priority</span></span>,<br />                       <span class="methodparam"><span class="type">void* </span><span class="parameter">data</span></span>);</code><p>Creates a new thread and returns its <span class="type">thread_id</span> identifier (a positive
integer). The arguments are:</p><table class="variablelist parameters"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="parameter">func</code></span></p></td><td><p>Is a pointer to a thread function. This is the function that the
thread will execute when it's told to run. See
"The Thread Function"
for details.</p></td></tr><tr><td><p><span class="term"><code class="parameter">name</code></span></p></td><td><p>Is the name that you wish to give the thread. It can be, at
most, <code class="constant">B_OS_NAME_LENGTH</code> (32) characters long.</p></td></tr><tr><td><p><span class="term"><code class="parameter">priority</code></span></p></td><td><p>Is the CPU priority level of the thread. This value should
be between 0 and 120; he higher the priority, the more attention the
thread gets. See
Thread Priorities
for a description of the priorities, and
Thread Priority Values
for a list of priority constants.</p></td></tr><tr><td><p><span class="term"><code class="parameter">data</code></span></p></td><td><p>Is forwarded as the argument to the thread function.</p></td></tr></tbody></table><p>A newly spawned thread is in a suspended state
(<code class="constant">B_THREAD_SUSPENDED</code>). To
tell the thread to run, you pass its <span class="type">thread_id</span> to the
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#resume_thread" title="resume_thread()"><code class="function">resume_thread()</code></a>
function. The thread will continue to run until the thread function
exits, or until the thread is explicitly killed (through a signal or a
call to <a class="link" href="TheKernelKit_ThreadsAndTeams.html#exit_thread" title="exit_thread(), kill_thread(), kill_team(), on_exit_thread()"><code class="function">exit_thread()</code></a>,
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#kill_thread"><code class="function">kill_thread()</code></a>, or
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#kill_team"><code class="function">kill_team()</code></a>).</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_NO_MORE_THREADS</code>.</span></p></td><td><p>All <span class="type">thread_id</span> numbers are currently in use.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>Not enough memory to allocate the resources for another
thread.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="suspend_thread"></a>suspend_thread()</h4></div></div></div><a id="id1110620" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">suspend_thread</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>);</code><p>Halts the execution of the given thread, but doesn't kill the thread
entirely. The thread remains suspended (<code class="function">suspend_thread()</code> blocks) until
it's told to run through the
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#resume_thread" title="resume_thread()"><code class="function">resume_thread()</code></a>
function. Nothing prevents you from suspending your own thread, i.e.:</p><pre class="programlisting example cpp"><code class="function">suspend_thread</code>(<code class="function">find_thread</code>(<code class="constant">NULL</code>));</pre><p>Of course, this is only smart if you have some other thread that will
resume you later.</p><p>You can suspend any thread, regardless of its current state. But be
careful: If the thread is blocked on a semaphore (for example), the
subsequent
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#resume_thread" title="resume_thread()"><code class="function">resume_thread()</code></a>
call will "hop over" the semaphore acquisition.</p><p>Suspensions don't nest. A single
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#resume_thread" title="resume_thread()"><code class="function">resume_thread()</code></a> unsuspends a thread
regardless of the number of <code class="function">suspend_thread()</code> calls it has received.</p><p><code class="function">suspend_thread()</code> is the same as sending a
<span class="signal">SIGSTOP</span> signal to the thread.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The thread is now suspended.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_ID</code>.</span></p></td><td><p>thread isn't a valid <span class="type">thread_id</span> number.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="wait_for_thread"></a>wait_for_thread()</h4></div></div></div><a id="id1110788" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">wait_for_thread</span>(<span class="methodparam"><span class="type">thread_id </span><span class="parameter">thread</span></span>,<br />                         <span class="methodparam"><span class="type">status_t* </span><span class="parameter">exit_value</span></span>);</code><p>This function causes the calling thread to wait until thread (the "target
thread") has died. If thread is suspended (or freshly spawned),
<code class="function">wait_for_thread()</code> will resume it.</p><p>When the target thread is dead, the value that was returned by its thread
function (or imposed by
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#exit_thread" title="exit_thread(), kill_thread(), kill_team(), on_exit_thread()"><code class="function">exit_thread()</code></a>)
is returned in <code class="parameter">exit_value</code>. If the
target thread was killed (by
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#kill_thread"><code class="function">kill_thread()</code></a> or
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#kill_team"><code class="function">kill_team()</code></a>),
or if the thread function doesn't return a value, the value returned in
<code class="parameter">exit_value</code> will be unreliable.</p><p>You must pass a valid pointer as the second argument to
<code class="function">wait_for_thread()</code>. You mustn't pass
<code class="constant">NULL</code> even if you're not interested in
the return value.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The target is now dead.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_THREAD_ID</code>.</span></p></td><td><p><code class="parameter">thread</code> isn't a valid
<span class="type">thread_id</span> number.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_INTERRUPTED</code>.</span></p></td><td><p>The target was killed by a signal. This includes
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#kill_thread"><code class="function">kill_thread()</code></a>,
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#kill_team"><code class="function">kill_team()</code></a>, and
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#exit_thread" title="exit_thread(), kill_thread(), kill_team(), on_exit_thread()"><code class="function">exit_thread()</code></a>.</p></td></tr></tbody></table></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="ThreadsAndTeams_DefinedTypes"></a>Thread and Team Structures and Types</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="team_id"></a><a id="thread_id"></a>
team_id, thread_id</h4></div></div></div><a id="id1110993" class="indexterm"></a><a id="id1111000" class="indexterm"></a><pre class="programlisting c">typedef <span class="type">int32</span> <span class="type">team_id</span> ;
typedef <span class="type">int32</span> <span class="type">thread_id</span> ;</pre><p>These id numbers uniquely identify teams and threads, respecitvely.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="team_info"></a>team_info</h4></div></div></div><a id="id1111042" class="indexterm"></a><pre class="programlisting c">typedef struct {
<span class="type">team_id</span> <code class="varname">team</code>;
<span class="type">int32</span> <code class="varname">thread_count</code>;
<span class="type">int32</span> <code class="varname">image_count</code>;
<span class="type">int32</span> <code class="varname">area_count</code>;
<span class="type">thread_id</span> <code class="varname">debugger_nub_thread</code>;
<span class="type">port_id</span> <code class="varname">debugger_nub_port</code>;
<span class="type">int32</span> <code class="varname">argc</code>;
<span class="type">char</span> <code class="varname">args</code>[64];
<span class="type">uid_t</span> <code class="varname">uid</code>;
<span class="type">gid_t</span> <code class="varname">gid</code>;
} <span class="type">team_info</span>;</pre><p>The <span class="type">team_info</span> structure returns information about a team. To retrieve one
of these structures, use
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#get_team_info" title="get_team_info(), get_next_team_info()"><code class="function">get_team_info()</code></a> or
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#get_next_team_info"><code class="function">get_next_team_info()</code></a>.</p><p>The first field is obvious; the next three reasonably so: They give the
number of threads that have been spawned, images that have been loaded,
and areas that have been created or cloned within this team.</p><p>The debugger fields are used by the, uhm, the…debugger?</p><p>The <code class="varname">argc</code> field is the number of command line arguments that were used to
launch the team; <code class="varname">args</code> is a copy of the first 64 characters from the
command line invocation. If this team is an application that was launched
through the user interface (by double-clicking, or by accepting a dropped
icon), then <code class="varname">argc</code> is 1 and <code class="varname">args</code> is the name of the application's
executable file.</p><p><code class="varname">uid</code> and <code class="varname">gid</code> identify the user
and group that "owns" the team. You can use
these values to play permission games.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="thread_func"></a>thread_func</h4></div></div></div><a id="id1111214" class="indexterm"></a><pre class="programlisting c">typedef <span class="type">int32</span> (*<span class="type">thread_func</span>)(<span class="type">void *</span><code class="parameter">data</code>);</pre><p><span class="type">thread_func</span> is the prototype for a thread's thread function. You specify
a thread function by passing a <span class="type">thread_func</span> as the first argument to
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#spawn_thread" title="spawn_thread()"><code class="function">spawn_thread()</code></a>;
the last argument to
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#spawn_thread" title="spawn_thread()"><code class="function">spawn_thread()</code></a>
is forwarded as the thread function's data argument. When the thread function exits, the
spawned thread is automatically killed. To retrieve a <span class="type">thread_func</span>'s
return value, some other thread must be waiting in a
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#wait_for_thread" title="wait_for_thread()"><code class="function">wait_for_thread()</code></a>
call.</p><p>Note that
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#spawn_thread" title="spawn_thread()"><code class="function">spawn_thread()</code></a>
doesn't copy the data that data points to. It
simply passes the pointer through literally. Never pass a pointer that's
allocated locally (on the stack).</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="thread_info"></a>thread_info</h4></div></div></div><a id="id1111303" class="indexterm"></a><pre class="programlisting c">typedef struct {
<span class="type">thread_id</span> <code class="varname">thread</code>;
<span class="type">team_id</span> <code class="varname">team</code>;
<span class="type">char</span> <code class="varname">name</code>[<code class="constant">B_OS_NAME_LENGTH</code>];
<span class="type">thread_state</span> <code class="varname">state</code>;
<span class="type">sem_id</span> <code class="varname">sem</code>;
<span class="type">int32</span> <code class="varname">priority</code>;
<span class="type">bigtime_t</span> <code class="varname">user_time</code>;
<span class="type">bigtime_t</span> <code class="varname">kernel_time</code>;
<span class="type">void *</span> <code class="varname">stack_base</code>;
<span class="type">void *</span> <code class="varname">stack_end</code>;
} <span class="type">thread_info</span></pre><p>The <span class="type">thread_info</span> structure contains information about a thread. To
retrieve one of these structure, use
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#get_thread_info" title="get_thread_info(), get_next_thread_info()"><code class="function">get_thread_info()</code></a> or
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#get_next_thread_info"><code class="function">get_next_thread_info()</code></a>.</p><p>The <code class="varname">thread</code>, <code class="varname">team</code>,
and <code class="varname">name</code> fields contain the indicated information.</p><p><code class="varname">state</code> describes what the thread is currently doing (see
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#thread_state" title="thread_state"><span class="type">thread_state</span></a> for
the list of states). If the thread is waiting to acquire a semaphore, sem
is that semaphore.</p><p><code class="varname">priority</code> is a value that indicates the level of attention the thread gets
(see Thread Priority).</p><p><code class="varname">user_time</code> and <code class="varname">kernel_time</code>
are the amounts of time, in microseconds, the
thread has spent executing user code and the amount of time the kernel
has run on the thread's behalf, respectively.</p><p><code class="varname">stack_base</code> and <code class="varname">stack_end</code>
are pointers to the first byte and last bytes in
the thread's execution stack. Currently, the stack size is fixed at
around 256k.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>The two stack pointers are currently inverted such that <code class="varname">stack_base</code> is
<span class="emphasis"><em>less</em></span> than <code class="varname">stack_end</code>.
(In a stack-grows-down world, the base should be
greater than the end.)</p></div></div></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="ThreadsAndTeams_Constants"></a>Thread and Team Constants</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="B_SYSTEM_TEAM"></a>B_SYSTEM_TEAM</h4></div></div></div><a id="id1111524" class="indexterm"></a><pre class="programlisting c">#define <code class="constant">B_SYSTEM_TEAM</code> ...</pre><p>Use this constant as the first argument to
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#get_team_info" title="get_team_info(), get_next_team_info()"><code class="function">get_team_info()</code></a>
to get team information about the kernel).</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="B_SYSTEM_TIMEBASE"></a>B_SYSTEM_TIMEBASE</h4></div></div></div><a id="id1111564" class="indexterm"></a><pre class="programlisting c">#define <code class="constant">B_SYSTEM_TIMEBASE</code> ...</pre><p>The system timebase constant is used as a basis for time measurement in
the <a class="link" href="TheKernelKit_ThreadsAndTeams.html#snooze_until"><code class="function">snooze_until()</code></a>
function. (Currently, it's the only timebase available.)</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="Constants_be_task_flags"></a><a id="B_DEFAULT_MEDIA_PRIORITY"></a>
<a id="B_OFFLINE_PROCESSING"></a>
<a id="B_STATUS_RENDERING"></a>
<a id="B_USER_INPUT_HANDLING"></a>
<a id="B_LIVE_VIDEO_MANIPULATION"></a>
<a id="B_VIDEO_PLAYBACK"></a>
<a id="B_VIDEO_RECORDING"></a>
<a id="B_LIVE_AUDIO_MANIPULATION"></a>
<a id="B_AUDIO_PLAYBACK"></a>
<a id="B_AUDIO_RECORDING"></a>
<a id="B_LIVE_3D_RENDERING"></a>
<a id="B_NUMBER_CRUNCHING"></a>
be_task_flags</h4></div></div></div><a id="id1111662" class="indexterm"></a><a id="id1111672" class="indexterm"></a><a id="id1111681" class="indexterm"></a><a id="id1111691" class="indexterm"></a><a id="id1111701" class="indexterm"></a><a id="id1111710" class="indexterm"></a><a id="id1111720" class="indexterm"></a><a id="id1111729" class="indexterm"></a><a id="id1111738" class="indexterm"></a><a id="id1111748" class="indexterm"></a><a id="id1111757" class="indexterm"></a><a id="id1111767" class="indexterm"></a><pre class="programlisting c">enum <span class="enum">be_task_flags</span> {
<code class="constant">B_DEFAULT_MEDIA_PRIORITY</code>,
<code class="constant">B_OFFLINE_PROCESSING</code>,
<code class="constant">B_STATUS_RENDERING</code>,
<code class="constant">B_USER_INPUT_HANDLING</code>,
<code class="constant">B_LIVE_VIDEO_MANIPULATION</code>,
<code class="constant">B_VIDEO_PLAYBACK</code>,
<code class="constant">B_VIDEO_RECORDING</code>,
<code class="constant">B_LIVE_AUDIO_MANIPULATION</code>,
<code class="constant">B_AUDIO_PLAYBACK</code>,
<code class="constant">B_AUDIO_RECORDING</code>,
<code class="constant">B_LIVE_3D_RENDERING</code>,
<code class="constant">B_NUMBER_CRUNCHING</code>
};</pre><p>Declared in: <code class="filename">kernel/scheduler.h</code></p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_DEFAULT_MEDIA_PRIORITY</code>.</span></p></td><td><p>The thread isn't doing anything specialized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_OFFLINE_PROCESSING</code>.</span></p></td><td><p>The thread is doing non-real-time computations.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_STATUS_RENDERING</code>.</span></p></td><td><p>The thread is rendering a status or preview display.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_USER_INPUT_HANDLING</code>.</span></p></td><td><p>The thread is handling user input.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LIVE_VIDEO_MANIPULATION</code>.</span></p></td><td><p>The thread is processing live video
(filtering, compression, decompression, etc.).</p></td></tr><tr><td><p><span class="term"><code class="constant">B_VIDEO_PLAYBACK</code>.</span></p></td><td><p>The thread is playing back video from a hardware device.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_VIDEO_RECORDING</code>.</span></p></td><td><p>The thread is recording video from a hardware device.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LIVE_AUDIO_MANIPULATION</code>.</span></p></td><td><p>The thread is doing real-time manipulation of
live audio data (filtering, compression, decompression, etc.).</p></td></tr><tr><td><p><span class="term"><code class="constant">B_AUDIO_PLAYBACK</code>.</span></p></td><td><p>The thread is playing back audio from a hardware device.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_AUDIO_RECORDING</code>.</span></p></td><td><p>The thread is recording audio from a hardware device.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LIVE_3D_RENDERING</code>.</span></p></td><td><p>The thread is performing live 3D rendering.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NUMBER_CRUNCHING</code>.</span></p></td><td><p>The thread is doing data processing.</p></td></tr></tbody></table><p>These constants describe what the thread is designed to do. You use these
constants when asking for a suggested priority (see
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#suggest_thread_priority"><code class="function">suggest_thread_priority()</code></a>).</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>These constants may not be used as actual thread priority
values—do not pass one of these values as the priority argument to
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#spawn_thread" title="spawn_thread()"><code class="function">spawn_thread()</code></a>.</p></div></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="Constants_ThreadPriorities"></a><a id="B_LOW_PRIORITY"></a>
<a id="B_NORMAL_PRIORITY"></a>
<a id="B_DISPLAY_PRIORITY"></a>
<a id="B_URGENT_DISPLAY_PRIORITY"></a>
<a id="B_REAL_TIME_DISPLAY_PRIORITY"></a>
<a id="B_URGENT_PRIORITY"></a>
<a id="B_REAL_TIME_PRIORITY"></a>
Thread Priority Values</h4></div></div></div><a id="id1112145" class="indexterm"></a><a id="id1112154" class="indexterm"></a><a id="id1112163" class="indexterm"></a><a id="id1112173" class="indexterm"></a><a id="id1112182" class="indexterm"></a><a id="id1112192" class="indexterm"></a><a id="id1112201" class="indexterm"></a><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Time-Sharing Priority</th><th>Value</th></tr></thead><tbody><tr><td><code class="constant">B_LOW_PRIORITY</code></td><td>5</td></tr><tr><td><code class="constant">B_NORMAL_PRIORITY</code></td><td>10</td></tr><tr><td><code class="constant">B_DISPLAY_PRIORITY</code></td><td>15</td></tr><tr><td><code class="constant">B_URGENT_DISPLAY_PRIORITY</code></td><td>20</td></tr></tbody></table></div><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Real-Time Priority</th><th>Value</th></tr></thead><tbody><tr><td><code class="constant">B_REAL_TIME_DISPLAY_PRIORITY</code></td><td>100</td></tr><tr><td><code class="constant">B_URGENT_PRIORITY</code></td><td>110</td></tr><tr><td><code class="constant">B_REAL_TIME_PRIORITY</code></td><td>120</td></tr></tbody></table></div><p>The thread priority values are used to set the "urgency" of a thread.
Although you can reset a thread's priority through
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#set_thread_priority" title="set_thread_priority(), suggest_thread_priority()"><code class="function">set_thread_priority()</code></a>,
the priority is initially—and almost always permanently—set
in <a class="link" href="TheKernelKit_ThreadsAndTeams.html#spawn_thread" title="spawn_thread()"><code class="function">spawn_thread()</code></a>.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="thread_state"></a><a id="B_THREAD_RUNNING"></a>
<a id="B_THREAD_READY"></a>
<a id="B_THREAD_SUSPENDED"></a>
<a id="B_THREAD_WAITING"></a>
<a id="B_THREAD_RECEIVING"></a>
<a id="B_THREAD_ASLEEP"></a>
thread_state</h4></div></div></div><a id="id1112448" class="indexterm"></a><a id="id1112455" class="indexterm"></a><a id="id1112465" class="indexterm"></a><a id="id1112474" class="indexterm"></a><a id="id1112483" class="indexterm"></a><a id="id1112493" class="indexterm"></a><a id="id1112502" class="indexterm"></a><pre class="programlisting c">enum { ... } <span class="type">thread_state</span></pre><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_THREAD_RUNNING</code>.</span></p></td><td><p>The thread is currently receiving attention from a CPU.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_THREAD_READY</code>.</span></p></td><td><p>The thread is waiting for its turn to receive attention.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_THREAD_SUSPENDED</code>.</span></p></td><td><p>The thread has been suspended or is freshly-spawned
and is waiting to start.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_THREAD_WAITING</code>.</span></p></td><td><p>The thread is waiting to acquire a semaphore. The <code class="varname">sem</code>
field of the thread's
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#thread_info" title="thread_info"><span class="type">thread_info</span></a>
structure will tell you which semaphore.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_THREAD_RECEIVING</code>.</span></p></td><td><p>The thread is sitting in a
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#receive_data" title="receive_data()"><code class="function">receive_data()</code></a>
function call.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_THREAD_ASLEEP</code>.</span></p></td><td><p>The thread is sitting in a
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#snooze" title="snooze(), snooze_until()"><code class="function">snooze()</code></a>
call.</p></td></tr></tbody></table><p>A thread's state tells you what the thread is currently doing. To get the
state, look in the state field of the
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#thread_info" title="thread_info"><span class="type">thread_info</span></a>
structure (retrieved through
<a class="link" href="TheKernelKit_ThreadsAndTeams.html#get_thread_info" title="get_thread_info(), get_next_thread_info()"><code class="function">get_thread_info()</code></a>).</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheKernelKit_Semaphores.html">Semaphores</a>  Up: <a href="TheKernelKit.html">The Kernel Kit</a>  Next: <a href="TheKernelKit_Time.html">Time Information</a> </div><div id="footerB"><div id="footerBL"><a href="TheKernelKit_Semaphores.html" title="Semaphores"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheKernelKit.html" title="The Kernel Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="TheKernelKit_Time.html" title="Time Information"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink