Source/DPCoroutine.h

   1 //
   2 //  DPCoroutine.h
   3 //  HigherOrderMessaging
   4 //
   5 //  Created by Ofri Wolfus on 01/08/07.
   6 //  Copyright 2007 Ofri Wolfus. All rights reserved.
   7 //
   8
   9 #import <Foundation/Foundation.h>
  10 #import "DPMessage.h"
  11 #import "DPMultiThreading.h"
  12 #import "Coro.h"
  13
  14
  15 @interface DPCoroutine : NSObject {
  16         int32_t _refCount;
  17         Coro *_coro;
  18         BOOL isActive;
  19         DPMessage *message;
  20         id target;
  21         DPCoroutine *parent;
  22 }
  23
  24 /*!
  25  * @abstract Returns the currently active coroutine in the current thread
  26  * or nil if no coroutine is active.
  27  */
  28 + (id)currentCoroutine;
  29
  30
  31 /*!
  32  * @abstract Creates and returns a new coroutine.
  33  *
  34  * @discussion The returned instance must be added to a <code>DPCoroutineStack</code>
  35  * in order to start execution.
  36  *
  37  * @param msg The message which its method will be executed as the coroutine's body.
  38  * @param target The object which will receiver the message.
  39  *
  40  * @result An initialized DPCoroutine instance or <code>nil</code> if either <code>msg</code>
  41  * or </code>target</code> is <code>nil</code>.
  42  */
  43 - (id)initWithMessage:(DPMessage *)msg target:(id)target;
  44
  45 /*!
  46  * @abstract Stops the execution of the receiver and passes control to the coroutine's stack.
  47  *
  48  * @discussion This method causes the receiver to save its current execution state and return
  49  * control to its stack. The receiver's coroutine stack then schedules the receiver to continue
  50  * execution later, and executes other coroutines until then.
  51  * Don't use this method unless you have to. Use the <code>DPCoroutineYield()</code> macro instead.
  52  */
  53 - (void)yield;
  54
  55 @end
  56
  57
  58 @interface DPCoroutineStack : DPRunLoopSource {
  59         OSSpinLock mainCorosLock;
  60         NSMutableDictionary *mainCoros;
  61         DPQueue *stack;
  62         DPQueue *unusedCoroutines;
  63         int32_t activeRoutines;
  64 }
  65
  66 /*!
  67  * @abstract Returns the current active stack in the current thread.
  68  */
  69 + (id)currentStack;
  70
  71 /*!
  72  * @abstract Sets the current stack.
  73  */
  74 + (void)setCurrentStack:(id)stack;
  75
  76 /*!
  77  * @abstract Returns the default coroutine stack of the main thread.
  78  */
  79 + (id)mainStack;
  80
  81
  82 /*!
  83  * @abstract Adds a coroutine to the receiver's queue, which will be
  84  * executed later.
  85  */
  86 - (void)addCoro:(DPCoroutine *)coro;
  87
  88 /*!
  89  * @abstract Executes the next coroutine in the queue.
  90  * @discussion You rarely, if ever, need to invoke this method directly.
  91  *
  92  * @result <code>YES</code> if the receiver processed a coroutine, <code>NO</code> otherwise.
  93  */
  94 - (BOOL)nextCoro;
  95
  96 /*!
  97  * @abstract Returns whether the receiver has coroutines to process or not.
  98  * @discussion Due to thread safety issues, this method may not always be accurate
  99  * and might return <code>YES</code> even if the receiver has no work.
 100  */
 101 - (BOOL)hasWork;
 102
 103 /*!
 104  * @abstract Makes the receiver process all its coroutines until they complete.
 105  *
 106  * @discussion This method starts a tight loop that exists only after all coroutines returned.
 107  * Don't invoke this method unless you're absolutely sure you need it.
 108  */
 109 - (void)empty;
 110
 111 @end
 112
 113
 114 @interface NSObject (DPCoroutine)
 115
 116 /*!
 117  * @abstract Creates a new coroutine with a given message and adds it to the current coroutine stack.
 118  *
 119  * @discussion This method does nothing if there's no active coroutine stack in the current thread.
 120  * A stack is automatically created for you in the main thread and added to the default runloop mode.
 121  * For threads you create yourself you must set up a stack by hand like this:
 122  *
 123  <code>
 124  - (void)startThreadMethod {
 125          NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
 126          DPCoroutineStack *stack = [[DPCoroutineStack alloc] init];
 127
 128          [DPCoroutineStack setCurrentStack:stack];
 129          [[NSRunLoop currentRunLoop] addSource:stack forMode:NSDefaultRunLoopMode];
 130          [[NSRunLoop currentRunLoop] run];
 131
 132          [stack release];
 133          [pool release];
 134  }
 135  </code>
 136  */
 137 - (void)coroutine:(DPMessage *)msg;
 138
 139 @end
 140
 141 #ifndef DPCoroutineYield
 142
 143 /*!
 144  * @abstract Stops execution of the current coroutine and passes control to another coroutine.
 145  */
 146 #define DPCoroutineYield() [[DPCoroutine currentCoroutine] yield]
 147 #endif