AMIGA - MEM_#?
 ----------------------------------------------------------------------------

   NAME

      mem_dosynctask() - Narrows task switching to selected
                         task.



   SYNOPSIS

      res = mem_dosynctask(addr);

      LONG mem_dosynctask(ULONG);



   FUNCTION

      This function allows exclusive interaction with given
      task by manipulating task priorities, so effectively
      it looks like 'Forbid()', but it is not!



   INPUTS

      addr   - Task address as integer. Passing NULL causes
               restore.



   RETURNS

      Returns 1 if synchronisation was attempted, 0 if it
      is in progress.



   BASES

      SysBase



   NOTES

      This function is very helpful when there is a need to
      detect when certain task gives away its CPU time.

      Do not use this function if you know that task youre
      trying to spy on never calls 'Wait()' or 'Signal()',
      either directly or indirectly and/or does not die or
      too dense signal(below 50 micros) is being delivered
      from interrupts. Machine lockup guaranteed!

      There is no way to tell whether 'Wait()' or 'Signal()'
      were called. Task will loose CPU in both cases!

      In order to stay in sync. you must call 'Forbid()' or
      'Disable()'(preferred) as soon as possible. This must
      be done right after calling this function ;-) . Then
      do what you want, except for 'Wait()' ing(directly or
      indirectly) and after that 'Permit()' or 'Enable()'.

      Task presence wont be assured! If 'addr' does not
      correspond any task, this func. will return at once.

      If this function is being used from concurrent tasks
      then it will block for the period of synchronisation
      in all other tasks, even in those who have advantage
      of priority!



   SEE ALSO

      mem_dosynctasks()



   EXAMPLE

      See 'testsuite/dosynctask-test.c' for more details.



   BUGS

      There is one, yes. There is workaround for it too. If
      task youre spying on 'Signal()'s some other task then
      two things may happen:

      1. You will resume, being sure activity ceased and
      if you did send a signal to terminate that task then
      after you are done that previously signaled task will
      resume.

      2. If that signalled task will be wanting to reply it
      may certainly not be able to find the caller anymore.

      What to do? Call 'mem_cooperate(-127, SIGF_SINGLE);'
      right after 'Signal()' which should be placed right
      after 'mem_dosynctask()', so you will pass your CPU
      time to that signalled task. This isnt without probs,
      cus others will also resume but works. If you want to
      be sure communication is complete try even -128. Do
      not worry priority related lockup is generally not
      possible in this state.

      Please note! Do not incorporate 'mem_cooperate()' in
      'mem_dosynctask()', make a wrapper instead, cus there
      must be two separate calls for this to work!



 ----------------------------------------------------------------------------