doc/apiref.html

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 12. GeekOS API Reference</title><meta name="generator" content="DocBook XSL Stylesheets V1.64.1"><link rel="home" href="index.html" title="Hacking GeekOS"><link rel="up" href="index.html" title="Hacking GeekOS"><link rel="previous" href="ipcproject.html" title="Chapter 11. Project 6: ACLs and Inter-process Communication"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. GeekOS API Reference</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ipcproject.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="apiref"></a>Chapter 12. GeekOS API Reference</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="apiref.html#threadfns">1. Thread functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="apiref.html#Start_Kernel_Thread">1.1. Start_Kernel_Thread()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Exit">1.2. Exit()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Join">1.3. Join()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Wait">1.4. Wait()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Wake_Up">1.5. Wake_Up()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Wake_Up_One">1.6. Wake_Up_One()</a></span></dt></dl></dd></dl></div><p>
This chapter documents commonly used functions in the GeekOS kernel.
Note that this chapter is likely to be incomplete.  You can always refer
directly to the GeekOS source code if you need more information on
a particular function.
</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="threadfns"></a>1. Thread functions</h2></div></div><div></div></div>
This section describes functions used to manage threads.

<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Start_Kernel_Thread"></a>1.1. Start_Kernel_Thread()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">struct Kernel_Thread *<b class="fsfunc">Start_Kernel_Thread</b>(</code></td><td><var class="pdparam">startFunc</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">arg</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">priority</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">detached</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td>Thread_Start_Func  </td><td><var class="pdparam">startFunc</var>;</td></tr><tr><td>ulong_t  </td><td><var class="pdparam">arg</var>;</td></tr><tr><td>int  </td><td><var class="pdparam">priority</var>;</td></tr><tr><td>bool  </td><td><var class="pdparam">detached</var>;</td></tr></table></div><p>
</p><p>
Starts a new kernel thread.  <i class="parameter"><tt>startFunc</tt></i> is a function
which will be called as the body of the new thread.
The start function will execute with interrupts enabled.
It should return void and take an unsigned long parameter.
<i class="parameter"><tt>arg</tt></i> is an arbitrary value passed to the thread's start function.
It can be used to convey extra information, or a pointer to a data
structure to be used by the thread.  <i class="parameter"><tt>priority</tt></i>
is the priority of the new thread.  <tt class="literal">PRIORITY_NORMAL</tt>
should be used for ordinary kernel threads.  <tt class="literal">PRIORITY_USER</tt>
should be used for user processes.  <i class="parameter"><tt>detached</tt></i>
indicates whether the parent thread will wait for the child thread
to exit.  If true, then the parent must call the <tt class="literal">Join()</tt>
function to wait for the child.  If false, then the parent must not
call <tt class="literal">Join()</tt>.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Exit"></a>1.2. Exit()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><p><code class="funcdef">void <b class="fsfunc">Exit</b>(</code><var class="pdparam">exitCode</var><code>)</code>;<br>int <code>exitCode</code>;</p></div><p>
</p><p>
Causes the current thread to exit with the exit code given by <i class="parameter"><tt>exitCode</tt></i>.
If the current thread has a parent and is not a detached thread, the
exit code will be returned by the <tt class="literal">Join()</tt> call made by
the parent.  Interrupts must be enabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Join"></a>1.3. Join()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><p><code class="funcdef">int <b class="fsfunc">Join</b>(</code><var class="pdparam">kthread</var><code>)</code>;<br>struct Kernel_Thread *<code>kthread</code>;</p></div><p>
</p><p>
Wait for a child thread <i class="parameter"><tt>kthread</tt></i> to exit.  The
child must have been created with its <i class="parameter"><tt>detached</tt></i>
parameter set to true.  Once the child has exited, returns the exit code
of the child thread.  Interrupts must be enabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Wait"></a>1.4. Wait()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><p><code class="funcdef">void <b class="fsfunc">Wait</b>(</code><var class="pdparam">waitQueue</var><code>)</code>;<br>struct Thread_Queue *<code>waitQueue</code>;</p></div><p>
</p><p>
Puts the current thread on given wait queue.  The thread will resume executing
at a later point when another thread or interrupt handler calls
<tt class="literal">Wake_Up()</tt> or <tt class="literal">Wake_Up_One()</tt> on the
same wait queue.  Interrupts must be disabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Wake_Up"></a>1.5. Wake_Up()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">void <b class="fsfunc">Wake_Up</b>(</code></td><td><var class="pdparam">waitQueue</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td>struct Thread_Queue * </td><td><var class="pdparam">waitQueue</var>;</td></tr></table></div><p>
</p><p>
Wakes up all threads on given wait queue by moving them to the
run queue.  Interrupts must be disabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Wake_Up_One"></a>1.6. Wake_Up_One()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">void <b class="fsfunc">Wake_Up_One</b>(</code></td><td><var class="pdparam">waitQueue</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td>struct Thread_Queue * </td><td><var class="pdparam">waitQueue</var>;</td></tr></table></div><p>
</p><p>
Wakes up the highest priority thread in given wait queue by
moving it to the run queue.  Interrupts must be disabled.
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ipcproject.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Chapter 11. Project 6: ACLs and Inter-process Communication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>