Thread: [Win32forth-cvs] win32forth/doc p-task.htm,NONE,1.1

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/win32forth/win32forth/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10806/win32forth/doc

Added Files:
	p-task.htm 
Log Message:
gah: Added documentation for task

--- NEW FILE: p-task.htm ---
<html>
<head>
<meta http-equiv="Content-Language" content="en-gb">
<meta name="GENERATOR" content="dexh00">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>
 W32F Task</title><style><!--
h1           { font-family: Tahoma; font-size: 24pt; font-weight: bold }
h2           { font-family: Tahoma; font-size: 18pt; font-weight: bold } -->
</style>
</head>
<body><h1 align="center">
<a href="mailto:win...@ya...?subject=DOC:Doc error in $Id: p-task.htm,v 1.1 2005/12/22 11:04:40 georgeahubert Exp $">
<img border="0" src="TELLUS.gif" align="left" width="32" height="32"></a>
<img border="0" src="FORTHPRO.gif"
width="32" height="32">&nbsp;&nbsp;Win32Forth</h1>
<hr /><h1>Using the Task Wordset
</h1><hr /><p>Multi-tasking in Win32Forth is accomplished by using the Windows<sub>® </sub>&nbsp;multi-tasker.
This is a pre-emptive multi-tasker.
</p><h2>Glossary
</h2><pre><b><a name="0">cell field+ task&gt;parm &nbsp;&nbsp;&nbsp;&nbsp;( task-block -- addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Convert the task-block address into the address of the thread parameter
</p><pre><b><a name="0">cell field+ task&gt;id &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( task-block -- addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Convert the task-block address into the address of the thread id
</p><pre><b><a name="0">cell field+ task&gt;handle &nbsp;&nbsp;( task-block -- addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Convert the task-block address into the address of the thread handle
</p><pre><b><a name="0">cell field+ task&gt;stop &nbsp;&nbsp;&nbsp;&nbsp;( task-block -- addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Convert the task-block address into the address of the the stop flag
</p><pre><b><a name="0">: task&gt;parm@ &nbsp;&nbsp;&nbsp;( task-block -- parm ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Fetch the parameter from the task-block.
</p><pre><b><a name="0">1 proc ExitThread as exit-task &nbsp;&nbsp;&nbsp;&nbsp;( n -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Exit the current task returning the value n to the operating system, which can be retrieved
by calling GetExitCodeThread. The stacks and user area for the thread are freed and
DLLs are detatched. If the thread is the last active thread of the process then the
process is terminated.
</p><pre><b><a name="0">: create-task &nbsp;&nbsp;( task-block -- flag ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Create a new task which is suspended. Flag is true if successful.
</p><pre><b><a name="0">: run-task &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( task-block -- flag ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Create a new task and run it. Flag is true if successful.
</p><pre><b><a name="0">: suspend-task &nbsp;( task-block -- flag ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Suspend a task. Flag is true if successful.
</p><pre><b><a name="0">: resume-task &nbsp;&nbsp;( task-block -- flag ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Resume a task. Flag is true if successful.
</p><pre><b><a name="0">: stop-task &nbsp;&nbsp;&nbsp;&nbsp;( task-block -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Set the stop flag of the task block to true.
</p><pre><b><a name="0">: task-sleep &nbsp;&nbsp;&nbsp;( n -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Suspend the current task for at least n msec. If n is INFINITE (-1) the task is suspended
forever.
</p><pre><b><a name="0">: (task-block) &nbsp;( parm cfa-task addr -- len ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Build a task block at the supplied address, initialise the parameter and xt and
return the size of the task block.
</p><pre><b><a name="0">: task-block &nbsp;&nbsp;&nbsp;( parm cfa-task -- addr ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Build a task block in the dictionary, initialise the parameter and xt and return
the address of the block.
</p><pre><b><a name="0">: task-stop? &nbsp;&nbsp;&nbsp;( task-block -- flag ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Task
</a></b></pre><p>Flag is true if stop-task has been set by another task. In this case the task should
do any necessary clean-up and exit.
</p><h2>Locking Resources
</h2><p>Since the multi-tasker is pre-emptive it is sometimes necessary to restrict access
to resources to a single task to prevent inteference between different tasks.
Win32Forth provides a set of words for efficiently locking sections of code.
The system also contains some locks used internally that are transparent to the user.
</p><h2>Glossary
</h2><pre><b><a name="0">: lock &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( lock -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;Lock
</a></b></pre><p>If another thread owns the lock wait until it's free,
then if the lock is free claim it for this thread,
then increment the lock count.
</p><pre><b><a name="0">: unlock &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( lock -- ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;&nbsp;Lock
</a></b></pre><p>Decrement the lock count and free the lock if the resultant count is zero.
</p><pre><b><a name="0">: trylock &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;( lock -- fl ) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\ W32F &nbsp;&nbsp;&nbsp;Lock
</a></b></pre><p><b>&nbsp;For NT 2000 and XP; </b>
If the lock is owned by another thread return false. <br />
If the lock is free claim it for this thread,
then increment the lock count and return true. <br />
<b>&nbsp;For Win9x; </b>
Perform the action of LOCK and return true.
</p><pre><b><a name="0">: make-lock &nbsp;&nbsp;&nbsp;&nbsp;( compiling: -&lt;name&gt;- &nbsp;-- &nbsp;runtime: -- lock ) \ W32F &nbsp;&nbsp;&nbsp;Lock
</a></b></pre><p>Create a new lock. When executed the lock returns it's identifier.
</p><h2>WARNING
</h2><p>Before using FORGET or executing MARKER words unlock any locks which are
about to be forgotten to avoid memory leaks AND exit any threads which will be
forgotten to avoid <b>&nbsp;CRASHING !! YOU HAVE BEEN WARNED </b>
</p><hr><p>Document $Id: p-task.htm,v 1.1 2005/12/22 11:04:40 georgeahubert Exp $</p>
</body></html>

Thread: [Win32forth-cvs] win32forth/doc p-task.htm,NONE,1.1

win32forth-cvs