home *** CD-ROM | disk | FTP | other *** search
/ Big Green CD 8 / BGCD_8_Dev.iso / NEXTSTEP / Examples / ThreadedApp-1.0.1 / ThreadedApp.h < prev    next >
Encoding:
Text File  |  1997-04-02  |  4.7 KB  |  124 lines
  1. /*
  2.  *  $Id: ThreadedApp.h,v 1.1 1997/04/02 18:28:51 croehrig Exp $
  3.  *
  4.  *  ThreadedApp:   adds support for a multi-threaded application.
  5.  *
  6.  *  (c) 1997 Chris Roehrig <croehrig@House.ORG>
  7.  *
  8.  *  This subclass of Application contains the functionality of the OpenStep
  9.  *  NSThread object, but in a place where (arguably) it makes more sense,
  10.  *  is cleaner, and is easier to use.
  11.  *
  12.  *  It also gives objects a "callback" mechanism so they can request
  13.  *  the main App thread to invoke their methods.   This makes for a
  14.  *  very clean synchronization mechanism with the AppKit as well as between
  15.  *  threads and in most cases should obviate the need to use any other 
  16.  *  synchronization mechanisms (locks, conditions, etc).
  17.  *
  18.  *  Only the main thread can use the AppKit, so all other threads must
  19.  *  message the main thread to do any functions (drawing, etc) that involve
  20.  *  the AppKit.   This service is provided by a callback mechanism via the
  21.  *  main event loop.
  22.  *  A subsidiary thread calls NXApp's callback:perform: method to cause
  23.  *  it to invoke a method under the main thread of execution.  The request
  24.  *  appears to the App as a special event which is handled through the main
  25.  *  windowserver event loop.
  26.  *
  27.  *  The callback:perform: methods are non-blocking: they don't wait for the 
  28.  *  invoked method to return.
  29.  *  
  30.  *  The callback:perform:wait: methods block until the main thread
  31.  *  has executed the method and returned the result.
  32.  *
  33.  *  There are two possible priority levels for the way the method is
  34.  *  invoked by the main thread (corresponding to the priority of the
  35.  *  event that appears in the event queue):
  36.  *   1   The base priority (NX_BASETHRESHOLD), which postpones the 
  37.  *       callback if the App is in a modal loop (attention panel, mouse
  38.  *       down, etc).   This can be used, for instance, if the child
  39.  *       thread wants to bring up its own interactive panel, but doesn't
  40.  *     want to interrupt anything important that the user might be doing.
  41.  *   2   The fast priority (NX_MODALRESPTHRESHOLD+1) which means the
  42.  *       event gets processed, even if the user is in a modal loop 
  43.  *       (mouse dragging, etc).   Use this for drawing in the background
  44.  *       and other activities which don't disturb the user's actions.
  45.  *       Fast priority callbacks CANNOT get events or use locks (CJRLock).
  46.  *
  47.  *  The ThreadedApp object uses the appDidInit: delegate method, so if your
  48.  *  application's delegate implements an appDidInit: method, be sure and
  49.  *  call [NXApp appDidInit:] from it.
  50.  *
  51.  */     
  52. #import <appkit/Application.h>
  53. #import <mach/cthreads.h>
  54.  
  55.  
  56. @interface ThreadedApp : Application
  57. {
  58. }
  59.  
  60.  
  61. - (void)detachNewThreadSelector:    (SEL)aSelector 
  62.             toTarget:    (id)aTarget 
  63.             withObject:    (id)anArgument;
  64. /*
  65.  *  Start the method in a new thread of execution.  The method is called
  66.  *  as in [aTarget perform:aSelector with:anArgument].   Any thread can
  67.  *  invoke this method.
  68.  */
  69.  
  70.  
  71. - (void)exitCurrentThread;
  72. /*
  73.  *  Exits the caller's thread of execution.
  74.  */
  75.  
  76.  
  77. - (void)sleepCurrentThread:(int)msec;
  78. /*
  79.  *  Performs a context switch and puts the current thread to sleep for
  80.  *  msec milliseconds.   Use this as an alternative to usleep
  81.  *  (which is not thread-safe).
  82.  */
  83.  
  84.  
  85. /*
  86.  * The following callback methods cause a method to be executed under the
  87.  * App's main thread of execution.  They behave similarly to Object's 
  88.  * perform:with: method except a target is also specified.   
  89.  * Any int-sized argument can be used and typecast to an id.
  90.  *
  91.  *  If a callback method is invoked from the main thread of execution,
  92.  *  the perform: method is directly used and no messages are sent.
  93.  *
  94.  * Typical usage is:
  95.  *     [NXApp callback:self perform:@selector(update:) with:self];
  96.  */
  97.  
  98. - (id)callbackAndWaitTarget:target perform:(SEL)aSel;
  99. - (id)callbackAndWaitTarget:target perform:(SEL)aSel with:anObject;
  100. - (void)callbackTarget:target perform:(SEL)aSel;
  101. - (void)callbackTarget:target perform:(SEL)aSel with:anObject;
  102.  
  103. - (id)safeCallbackAndWaitTarget:target perform:(SEL)aSel;
  104. - (id)safeCallbackAndWaitTarget:(id)target perform:(SEL)aSel with:(id)anObject;
  105. - (void)safeCallbackTarget:target perform:(SEL)aSel;
  106. - (void)safeCallbackTarget:(id)target perform:(SEL)aSel with:(id)anObject;
  107.  
  108. - (id)slowCallbackAndWaitTarget:target perform:(SEL)aSel;
  109. - (id)slowCallbackAndWaitTarget:(id)target perform:(SEL)aSel with:(id)anObject;
  110. - (void)slowCallbackTarget:target perform:(SEL)aSel;
  111. - (void)slowCallbackTarget:(id)target perform:(SEL)aSel with:(id)anObject;
  112.  
  113.  
  114. @end
  115.  
  116.  
  117. // Private methods in a category for CJRLock...
  118. @interface ThreadedApp(CJRLock) 
  119. - (void)lock: (mutex_t)mutex;
  120. - (void)lock: (mutex_t)mutex whenCondition: (condition_t)cond
  121.         withData:(volatile int *)data is:(int)value;
  122. - (void)threadDidUnlock:sender;
  123. @end
  124.