[Win32forth-cvs] win32forth/src/lib task.f,1.4,1.5

[George H. <geo...@us...>]

Update of /cvsroot/win32forth/win32forth/src/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10007/win32forth/src/lib

Modified Files:
	task.f 
Log Message:
gah: More documentation on multi-tasking.

Index: task.f
===================================================================
RCS file: /cvsroot/win32forth/win32forth/src/lib/task.f,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** task.f	22 Dec 2005 11:02:28 -0000	1.4
--- task.f	3 Jan 2006 08:28:19 -0000	1.5
***************
*** 8,14 ****
--- 8,49 ----
  \ *T Using the Task Wordset
  
+ \ *P The multi-tasker is not loaded in the system by default so the file TASK.F in the lib
+ \ ** folder should be included in any program that multi-tasks, unless using the file
+ \ ** MULTITHR.F (also in the lib folder) which includes it automatically.
  \ *P Multi-tasking in Win32Forth is accomplished by using the Windows\_® \d multi-tasker.
  \ ** This is a pre-emptive multi-tasker.
  
+ \ *S The Task Control Block
+ 
+ \ *P The task control block (also known as task-block or TCB) is a small structure either
+ \ ** alloted in the dictionary or allocated on the heap containing information about a task.
+ \ *B The xt and parameter variables are set when the task-block is created.
+ \ *B The stop flag can be set by other tasks and is used to signal the task that it has
+ \ ** been asked to finish.
+ \ *B The ID is set when the task is created and is valid only until the task terminates.
+ \ *B The handle is set when the task is created and is valid until it is closed by the
+ \ ** API CloseHandle function, even after the task has terminated. The operating system
+ \ ** does not free the OS resources allocated to a task until all handles (except for
+ \ ** the pseudohandle returned by the API GetCurrentThread) are closed and
+ \ ** the task has terminated. Programs should close the handle as soon as it's no longer
+ \ ** needed (if it's never used close it at the start of the task word).
+ 
+ \ *S The User Area
+ 
+ \ *P When a task is created the operating system allocates a stack for the task.
+ \ ** Win32Forth splits this stack into three regions, a return stack, a User area
+ \ ** and a data stack. The address of this User area is stored in thread local
+ \ ** storage so that callbacks have access to the correct User area for the task
+ \ ** (Versions prior to V6.05 always used the main task's User area for callbacks).
+ \ ** When a task starts the contents of the User area are undefined except
+ \ *B Base is set to decimal.
+ \ *B The exception handler is set so the task exits if an exception is thrown, returning
+ \ ** the error code to the operating system.
+ \ *B TCB is set to the task control block of the task.
+ \ *B RP0 is set to the base of the return stack.
+ \ *B SP0 is set to the base of the data stack.
+ \ *P All other User variables used by a task should be explicitly set before use.
+ \ ** If the task uses floating-point words then FINIT should be called first.
+ 
  \ *S Glossary