home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 (Developer) / NS_dev_3.2.iso / NextDeveloper / Headers / machkit / NXLock.h < prev    next >
Text File  |  1992-12-16  |  4KB  |  156 lines
  1. /*  Copyright (c) 1991, 1992 NeXT Computer, Inc.  All rights reserved. 
  2.  *
  3.  * NXLock.h. Standard lock object.
  4.  *
  5.  */
  6.  
  7. @protocol NXLock
  8. - lock;     // acquire lock (enter critical section)
  9. - unlock;   // release lock (leave critical section)
  10. @end
  11.  
  12. /* Lock protocol
  13.  *      send "lock" message upon entering critical section
  14.  *      send "unlock" message to leave critical section
  15.  *
  16.  * There are four classes with different implementations and
  17.  * performance characteristics.  There are example usages preceeding
  18.  * each class definition.
  19.  *
  20.  * Use NXLock to protect regions of code that can consume long
  21.  * periods of time (disk I/O, heavy computation.
  22.  *
  23.  * Use NXConditionLock for those cases where you wish only certain threads
  24.  * to awaken based on some condition you define, or for those cases
  25.  * when you have both short and long critical sections.
  26.  *
  27.  * Use NXSpinLock to protect short regions of critical code
  28.  * (short in terms of time spent in the region). Useful primarily on
  29.  * multiple processors.
  30.  *
  31.  * Use NXRecursiveLock to protect regions of code or data that may
  32.  * be accessed by the same thread.  The lock will not block if it
  33.  * is already held by the same thread.  This does not provide mutual
  34.  * exclusion with naive signal handlers...
  35.  *
  36.  */
  37.  
  38. #import <objc/Object.h>
  39.  
  40. /* NXSpinLock
  41.  * used to protect global objects held for short periods
  42.  *  NXSpinLock  *glob = [NXSpinLock new];   // done once!
  43.  *
  44.  *  [glob lock];
  45.  *  ... fuss with global data
  46.  *  [glob unlock];
  47.  */
  48.  
  49. @interface NXSpinLock : Object <NXLock> {
  50.     void *      _priv;
  51. }
  52. @end
  53.  
  54.  
  55. /*
  56.  * Usage:
  57.  * 
  58.  * Producer:
  59.  *
  60.  *  id condLock = [NXConditionLock new];
  61.  *  [condLock lock];
  62.  *  ...manipulate global data...
  63.  *  [condLock unlockWith:NEW_STATE];
  64.  *
  65.  * Consumer:
  66.  *  
  67.  *  ...The following sleeps until the producer does the unlockWith: such
  68.  *     that DESIRED_STATE == NEW_STATE.
  69.  *  [condLock lockWhen:DESIRED_STATE];
  70.  *  ...manipulate global data if necessary...
  71.  *  [condLock unlock];
  72.  *
  73.  *  ...OR...
  74.  *
  75.  *  [condLock lockWhen:DESIRED_STATE];
  76.  *  ...manipulate global data if necessary, then notify other lock users
  77.  *     of change of state.
  78.  *  [condLock unlockWith:NEW_STATE];
  79.  *
  80.  * The value of 'condition' is user-dependent.
  81.  *
  82.  * All 4 combinations of {lock,lockUntil} and {unlock,unlockWith} are legal,
  83.  * i.e.,
  84.  *  {
  85.  *      [condLock lock];
  86.  *      ...
  87.  *      [condLock unlock];
  88.  *  }
  89.  *  
  90.  *  {
  91.  *      [condLock lockWhen:SOME_CONDITION];
  92.  *      ...
  93.  *      [condLock unlock];
  94.  *  }
  95.  *
  96.  *  {
  97.  *      [condLock lock];
  98.  *      ...
  99.  *      [condLock unlockWith:SOME_CONDITION];
  100.  *  }
  101.  *
  102.  *  {
  103.  *      [condLock lockWhen:SOME_CONDITION];
  104.  *      ...
  105.  *      [condLock unlockWith:ANOTHER_CONDITION];
  106.  *  }
  107.  */
  108.  
  109. @interface NXConditionLock : Object <NXLock> {
  110.     void    *_priv;
  111. }
  112.  
  113. - initWith : (int)condition;        // init & set condition variable
  114. - (int) condition;
  115. - lockWhen : (int)condition;        // acquire lock when 
  116.                     //   conditionVar == condition
  117. - unlockWith : (int)condition;      // release lock and update conditionVar
  118.  
  119. @end
  120.  
  121.  
  122.  
  123. /* NXLock
  124.  * usage for objects held for longer periods (I/O, heavy computation, ...)
  125.  *
  126.  *  NXLock  *glob = [NXLock new];       // done once!
  127.  *
  128.  *  [glob lock];
  129.  *  ... long time of fussing with global data
  130.  *  [glob unlock];
  131.  */
  132.  
  133. @interface NXLock : Object <NXLock> {
  134.     void    *_priv;
  135. }
  136.  
  137. @end
  138.  
  139. /* NXRecursiveLock
  140.  * used for locks that need to be reacquired by the same thread 
  141.  *
  142.  *  NXRecursiveLock  *glob = [NXRecursiveLock new];       // done once!
  143.  *
  144.  *  [glob lock];
  145.  *  ... long time of fussing with global data
  146.  *        [glob lock] from some interior routine
  147.  *        [glob unlock] 
  148.  *  [glob unlock];
  149.  */
  150.     
  151. @interface NXRecursiveLock : Object <NXLock> {
  152.     void    *_priv;
  153. }
  154.  
  155. @end
  156.