win32forth-cvs

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

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

Modified Files:
	task.f 
Log Message:
gah: Added documentation for dexh to task.f and minor spelling correction

Index: task.f
===================================================================
RCS file: /cvsroot/win32forth/win32forth/src/lib/task.f,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** task.f	29 Aug 2005 15:56:28 -0000	1.3
--- task.f	22 Dec 2005 11:02:28 -0000	1.4
***************
*** 5,23 ****
  cr .( Loading Task Support...)
  
  \ -------------------- Task Control Block Offsets --------------------
  
  cell checkstack
! cell field+ task>parm     ( thread -- addr )             \ thread parameter
! cell field+ task>id       ( thread -- addr )             \ thread id
! cell field+ task>handle   ( thread -- addr )             \ thread handle
! cell field+ task>stop     ( thread -- addr )             \ the stop flag
  drop
  
! : task>parm@    ( task-block -- parm )         \ extract the parameter
                  task>parm @ ;
  
  \ -------------------- Task Start Initialisation --------------------
  
! 1 proc ExitThread as exit-task     ( n -- )     \ exit the thread
  
  : (task)        ( parm cfa -- )                 \ helper routine
--- 5,40 ----
  cr .( Loading Task Support...)
  
+ \ *! doc\p-task W32F Task
+ \ *T Using the Task Wordset
+ 
+ \ *P Multi-tasking in Win32Forth is accomplished by using the Windows\_® \d multi-tasker.
+ \ ** This is a pre-emptive multi-tasker.
+ 
+ \ *S Glossary
+ 
  \ -------------------- Task Control Block Offsets --------------------
  
  cell checkstack
! cell field+ task>parm     ( task-block -- addr )             \ W32F    Task
! \ *G Convert the task-block address into the address of the thread parameter
! cell field+ task>id       ( task-block -- addr )             \ W32F    Task
! \ *G Convert the task-block address into the address of the thread id
! cell field+ task>handle   ( task-block -- addr )             \ W32F    Task
! \ *G Convert the task-block address into the address of the thread handle
! cell field+ task>stop     ( task-block -- addr )             \ W32F    Task
! \ *G Convert the task-block address into the address of the the stop flag
  drop
  
! : task>parm@    ( task-block -- parm )                       \ W32F    Task
! \ *G Fetch the parameter from the task-block.
                  task>parm @ ;
  
  \ -------------------- Task Start Initialisation --------------------
  
! 1 proc ExitThread as exit-task     ( n -- )                  \ W32F    Task
! \ *G 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.
  
  : (task)        ( parm cfa -- )                 \ helper routine
***************
*** 43,47 ****
  \ -------------------- Task Management  --------------------
  
! : (create-task) ( addr state -- flag )          \ create a task
                  swap                            \ state addr
                  dup task>stop off               \ turn off stop flag
--- 60,64 ----
  \ -------------------- Task Management  --------------------
  
! : (create-task) ( thread state -- flag )          \ create a task
                  swap                            \ state addr
                  dup task>stop off               \ turn off stop flag
***************
*** 56,80 ****
                  0<> ;                           \ and set the flag, true=ok
  
! : create-task   ( addr -- flag )                \ create task suspended
                  CREATE_SUSPENDED (create-task) ;
  
! : run-task      ( addr -- flag )                \ create task running
                  0 (create-task) ;
  
! : suspend-task  ( addr -- flag )                \ suspend a task
                  task>handle @                   \ point at thread handle
                  call SuspendThread -1 <> ;      \ true=0K
  
! : resume-task   ( addr -- flag )                \ suspend a task
                  task>handle @                   \ point at thread handle
                  call ResumeThread -1 <> ;       \ true=0K
  
! : stop-task     ( addr -- )                     \ stop the task
                  task>stop on ;                  \ stop flag
  
! : task-sleep    ( n -- )                        \ sleep the task for n ms
                  call Sleep drop ;
  
! : (task-block)  ( parm cfa-task addr -- len )   \ build a task block at addr
                  dup>r !                         \ cfa
                  r@ cell+ !                      \ parameter for the task
--- 73,106 ----
                  0<> ;                           \ and set the flag, true=ok
  
! : create-task   ( task-block -- flag )                       \ W32F    Task
! \ *G Create a new task which is suspended. Flag is true if successful.
                  CREATE_SUSPENDED (create-task) ;
  
! : run-task      ( task-block -- flag )                       \ W32F    Task
! \ *G Create a new task and run it. Flag is true if successful.
                  0 (create-task) ;
  
! : suspend-task  ( task-block -- flag )                       \ W32F    Task
! \ *G Suspend a task. Flag is true if successful.
                  task>handle @                   \ point at thread handle
                  call SuspendThread -1 <> ;      \ true=0K
  
! : resume-task   ( task-block -- flag )                       \ W32F    Task
! \ *G Resume a task. Flag is true if successful.
                  task>handle @                   \ point at thread handle
                  call ResumeThread -1 <> ;       \ true=0K
  
! : stop-task     ( task-block -- )                            \ W32F    Task
! \ *G Set the stop flag of the task block to true.
                  task>stop on ;                  \ stop flag
  
! : task-sleep    ( n -- )                                     \ W32F    Task
! \ *G Suspend the current task for at least n msec. If n is INFINITE (-1) the task is suspended
! \ ** forever.
                  call Sleep drop ;
  
! : (task-block)  ( parm cfa-task addr -- len )                \ W32F    Task
! \ *G Build a task block at the supplied address, initialise the parameter and xt and
! \ ** return the size of the task block.
                  dup>r !                         \ cfa
                  r@ cell+ !                      \ parameter for the task
***************
*** 85,89 ****
                  ;
  
! : task-block    ( parm cfa-task -- addr )       \ a task-block
                  here >r                         \ return this block's address
                  ,                               \ cfa to execute as task
--- 111,117 ----
                  ;
  
! : task-block    ( parm cfa-task -- addr )                    \ W32F    Task
! \ *G Build a task block in the dictionary, initialise the parameter and xt and return
! \ ** the address of the block.
                  here >r                         \ return this block's address
                  ,                               \ cfa to execute as task
***************
*** 94,98 ****
                  r> ;                            \ return structure
  
! : task-stop?    ( task-block -- )               \ pause, stop if we're told
                  task>stop @ ;                   \ check, exit if stop set
  
--- 122,128 ----
                  r> ;                            \ return structure
  
! : task-stop?    ( task-block -- flag )                       \ W32F    Task
! \ *G 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.
                  task>stop @ ;                   \ check, exit if stop set
  
***************
*** 107,122 ****
  external
  
! : lock          ( lock -- )                    \ lock on a lock
                  call EnterCriticalSection drop ;
  
! : unlock        ( lock -- )                    \ unlock a lock
                  call LeaveCriticalSection drop ;
  
! : trylock       ( lock -- fl )                 \ try a lock
!                 call TryEnterCriticalSection 0<> ;  \ 0 -- lock is blocked
  
  internal
  
! : init-lock     ( lock -- )
                  0 swap call InitializeCriticalSectionAndSpinCount drop ;
  
--- 137,171 ----
  external
  
! \ *S Locking Resources
! 
! \ *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.
! 
! \ *S Glossary
! 
! : lock          ( lock -- )                                  \ W32F     Lock
! \ *G 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.
                  call EnterCriticalSection drop ;
  
! : unlock        ( lock -- )                                  \ W32F     Lock
! \ *G Decrement the lock count and free the lock if the resultant count is zero.
                  call LeaveCriticalSection drop ;
  
! : trylock       ( lock -- fl )                                \ W32F    Lock
! \ *G \b For NT 2000 and XP; \d
! \ ** If the lock is owned by another thread return false. \n
! \ ** If the lock is free claim it for this thread,
! \ ** then increment the lock count and return true. \n
! \ ** \b For Win9x; \d
! \ ** Perform the action of LOCK and return true.
!                 call TryEnterCriticalSection 0<> ;
  
  internal
  
! : init-lock     ( lock -- )     \ Initialise a lock
                  0 swap call InitializeCriticalSectionAndSpinCount drop ;
  
***************
*** 125,129 ****
  in-system
  
! : make-lock       ( -<name>-  -- )                \ create a lock
                  create
                  here lock-size ( 6 cells ) allot  \ gah
--- 174,179 ----
  in-system
  
! : make-lock     ( compiling: -<name>-  --  runtime: -- lock ) \ W32F    Lock
! \ *G Create a new lock. When executed the lock returns it's identifier.
                  create
                  here lock-size ( 6 cells ) allot  \ gah
***************
*** 135,142 ****
  internal
  
! : init-lock-from-list ( addr -- )
                  lock-size - init-lock ;
  
! : init-locks 
                  ['] init-lock-from-list lock-list do-link ;
  
--- 185,192 ----
  internal
  
! : init-lock-from-list ( addr -- )  \ Initialise a lock given address of link
                  lock-size - init-lock ;
  
! : init-locks          ( -- )       \ Initialise all the locks
                  ['] init-lock-from-list lock-list do-link ;
  
***************
*** 172,178 ****
  \ -------------------- Forgetting Locks -----------------------------
  
! \ WARNING 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 CRASHING !! YOU HAVE BEEN WARNED
  
  in-system
--- 222,229 ----
  \ -------------------- Forgetting Locks -----------------------------
  
! \ *S WARNING
! \ *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 CRASHING !! YOU HAVE BEEN WARNED \d
  
  in-system
***************
*** 190,191 ****
--- 241,243 ----
  module
  
+ \ *Z